Update README.md

README.md

@@ -3,66 +3,142 @@ pyFoamd
 
 Pythonic modification of OpenFOAM dictionaries and case files.
 
+Features
+--------
+
+* Load OpenFOAM cases as Python objects
+* Read and edit OpenFOAM dictionary entries
+* Manipulated OpenFOAM cases from command line using the integrated iPython console
+* Manipulate OpenFOAM cases from a Python script file.
+* Support for most OpenFOAM naitive types including:
+    * dictonary entries, lists, scalars, vectors, tensors, dimensioned types, tables, coded objects, and more
+* Run OpenFOAM case Allrun scripts
+* Easily setup and execute parametric OpenFOAM studies with many simulations     
+
 Installation
 ------------
 
-.. code-block:: bash
-
-    python -m pip install pyfoamd
+```bash
+python -m pip install pyfoamd
+```
 
 Basic Usage
 -----------
 
 Copy a template case and load as a python object
 
-.. code-block:: bash
-
-    cp $FOAM_TUTORIALS/incompressible/simpleFoam/pitzDaily .
-    cd pitzDaily
-    pf init
+```bash
+cp $FOAM_TUTORIALS/incompressible/simpleFoam/pitzDaily .
+cd pitzDaily
+pf init
+```
 
 View case variables
 
-.. code-block:: bash
-
-    pf edit
-
-.. code-block:: python
 
-    >>> case.constant.turbulenceProperties.RAS.RASModel
-    kEpsilon
+```bash
+pf edit
+```
 
+```python
+>>> case.constant.turbulenceProperties.RAS.RASModel
+kEpsilon
+```
 Change case dictionary entries
 
-.. code-block:: python
-
-    >>> case.constant.case.constant.turbulenceProperties.RAS.RASModel = kOmega
+```python
+>>> case.constant.case.constant.turbulenceProperties.RAS.RASModel = kOmega
+```
 
 Write the updated case to file
 
-.. code-block:: python
-
-    >>> case.write()
+```python
+>>> case.write()
+```
 
 Run the Allrun script
 
-.. code-block:: python
+```python
+>>> case.run()
+```
 
-    >>> case.run()
+Scripting
+---------
+
+PyFoamd can also be imported into a python script to allow for manipultion of OpenFOAM cases.  This is useful, for example, when performing parameteric studies to run multiple simulations with varibale parameters (e.g. different turbulence models):
+
+```bash
+#- Setup the OpenFOAM study directory
+cd ~
+mkdir ofStudy
+cd ofStudy
+cp $FOAM_TEMPLATES/incompressible/simpleFoam/pitzDaily of.template
+touch runStudy.py
+```
+
+runStudy.py
+```python
+import pyfoamd.functions as pf
+import pyfoamd.types as pt
+import pamdas as pd
+
+turbulenceModels = [kEpsilon, realizableKE, kOmega, kOmegaSST]
+parameterNames = ['Turbulence Model']
+
+samples = pd.DataFrame(
+    [[model] for model in turbulenceModels],
+    columns = parameterNames
+)
+
+def updateCase(case, values):
+    """
+    This function is called from the ofStudy.
+
+    Parameters
+    ----------
+    case [pyfoamd.ofCase]:
+        The OpenFOAM case which is to be updated.
+    values [list]:
+        Sample point as a list of dictionary values to be updated for the current simulation
+
+    Return
+    ------
+    case [pyfoamd.ofCase]:
+        The updated OpenFOAM case.
+        
+    """
+    turbModel = values[0]
+
+    case.constant.case.constant.turbulenceProperties.RAS.RASModel = turbModel
+
+    return case
+
+#- Create the OpenFOAM study
+study = pt.ofStudy('of.template', parameterNames, sample, updateCase)
+
+#- Run all 4 simulations
+study.run()
+
+```
+
+```bash
+# Run the study
+python runStudy.py
+```
 
 Releasing
 ---------
 
 Releases are published automatically when a tag is pushed to GitHub.
 
-.. code-block:: bash
-
-   # Set next version number
-   export RELEASE=x.x.x
+```bash
+# Set next version number
+export RELEASE=x.x.x
 
-   # Create tags
-   git commit --allow-empty -m "Release $RELEASE"
-   git tag -a $RELEASE -m "Version $RELEASE"
+# Create tags
+git commit --allow-empty -m "Release $RELEASE"
+git tag -a $RELEASE -m "Version $RELEASE"
 
-   # Push
-   git push upstream --tags
+# Push
+git push upstream --tags
+```