.. _`chapter:utilities`:

Utilities
=========

Figure `1.1 <#dirtree:utilities>`__ shows the architecture of
**utilities**.

.. container:: float
   :name: dirtree:utilities

   .. container:: minipage

.. _`sec:utilities:meshPorosity`:

meshPorosity
------------

**meshPorosity** is a post-processor that computes and print the total
volume, fibers volume, voids volume and porosity. It works considering
that the total domain is composed by a porous domain surrounded by two
buffer zones. To identify the porous domain, the script search for a
patch named **fibres**. This utility also works in the case of a porous
domain only (no buffer zones). In this configuration, the **fibres**
patch is useless. Listing `[lis:meshPorosity] <#lis:meshPorosity>`__
shows **meshPorosity** usage.

.. code:: bash

   $ meshPorosity

.. _`sec:utilities:patoManager`:

patoManager
-----------

| Listing `[lis:help] <#lis:help>`__ shows how to print the
  **patoManager** help.

.. code:: bash

   $ patoManager -h
   Usage: patoManager [OPTIONS]
   options:
     -addAllTests      Add all the new test files (*.C) from
                       "$LIB_PATO/src/applications/tests/testsuites" 
                       to the unit testing framework
     -addBC <oldBCName/newBCName>
                       Add new BC (copy of old BC)
     -addType <modelName/oldTypeName/newTypeName>
                       Add new type (copy of old type)
     -cleanTuto <tutoDir>
                       Clean the tutorials in <tutoDir> 
                       (N.B. use "all" to clean
                       all the tutorials)
     -listModels       List the available models
     -listTypes        List the available models and related types
     -removeBC <BCName>
                       Remove BC
     -removeType <modelName/typeName>
                       Remove type
     -runTest <args>   Run unit test suites
     -runTuto <tutoDir>
                       Run the tutorials in <tutoDir> 
                       (N.B. use "all" to run all
                       the tutorials)
     -saveTest <tutoDir>
                       Save the reference tutorials from <tutoDir> to
                       $PATO_DIR/src/applications/tests/
                       testsuites/tutorials/ref
     -showDoc <browser>
                       Show PATO documentation generated by Doxygen

Cleaning/running tutorials
~~~~~~~~~~~~~~~~~~~~~~~~~~

Listing `[lis:runTuto] <#lis:runTuto>`__ shows how to run all the
tutorials in the tutorials/1D folder. Listing
`[lis:cleanTuto] <#lis:cleanTuto>`__ shows how to clean all the
tutorials in the tutorials/1D folder.

.. code:: bash

   $ patoManager -runTuto "1D"

.. code:: bash

   $ patoManager -cleanTuto "1D"

Adding/removing types
~~~~~~~~~~~~~~~~~~~~~

Listing `[lis:models] <#lis:models>`__ shows how to list the different
material sub-models. Listing `[lis:types] <#lis:types>`__ shows how to
list the different types per material sub-model. Listing
`[lis:addType] <#lis:addType>`__ shows how to add a new type based on a
old type of a given material sub-model. Listing
`[lis:addType] <#lis:addType>`__ shows how to remove a type based of a
given material sub-model.

.. code:: bash

   $ patoManager -listModels
       Available models are:
           9
           (
               Energy
               GasProperties
               IO
               Mass
               MaterialChemistry
               MaterialProperties
               Pyrolysis
               TimeControl
               VolumeAblation
           )

.. code:: bash

   $ patoManager -listTypes
       Available types for EnergyModel:
           7
           (
               BoundaryTable
               CorrectBC
               FixedTemperature
               PureConduction
               Pyrolysis
               Pyrolysis_Heterogeneous_SpeciesDiffusion
               no
           )
       ...

.. code:: bash

   $ patoManager -addType "Energy/Pyrolysis/newModelName"

.. code:: bash

   $ patoManager -removeType "Energy/modelName"

Adding boundary conditions
~~~~~~~~~~~~~~~~~~~~~~~~~~

Listing `[lis:addBC] <#lis:addBC>`__ shows how to add new boundary
conditions based on old ones.

.. code:: bash

   $ patoManager -addBC "speciesBC/newBCname"

Showing Doxygen documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Listing `[lis:showdoc] <#lis:showdoc>`__ shows how to display the PATO
Doxygen documentation.

.. code:: bash

   $ patoManager -showDoc "firefox"

.. _`sec:utilities:inletPower`:

inletPower
----------

**inletPower** is a post-processor that computes the power on a
specified field. Reference temperature, patch and temperature field name
should be provided. You should provide the region name. You can select
which time step you want to post process.
Listing `[lis:inletPower] <#lis:inletPower>`__ shows **inletPower**
usage.

.. code:: bash

   $ inletPower -Tfield "Ta" -Tref 300 -field "U" "patch"

.. _`sec:utilities:storedEnergy`:

storedEnergy
------------

**storedEnergy** is a post-processor that computes the stored energy on
solid phase. Reference temperature, temperature field name and region
name should be provided. You can select which time step you want to post
process. Listing `[lis:storedEnergy] <#lis:storedEnergy>`__ shows
**storedEnergy** usage.

.. code:: bash

   $ storedEnergy -Tfield "Ta"

.. _`sec:utilities:postProcessTime`:

postProcessTime
---------------

**postProcessTime** creates a file that contains field values as a
function of time from the files in **postProcessing** directory.
Listing `[lis:postProcessTime] <#lis:postProcessTime>`__ shows
**postProcessTime** usage.

.. code:: bash

   $ postProcessTime "dictName" "regionName" "inputFileName" "outputFileName"

.. _`sec:utilities:processSets`:

processSets
-----------

**processSets** is run after OpenFOAM post-processor **sample** to grab
**cloud** data in the **sets** directory and rewrite them in a single
file. Currently, it can only extract data from *list_Ta_rho_s* file.
Listing `[lis:processSets] <#lis:processSets>`__ shows **processSets**
usage.

.. code:: bash

   $ processSets

.. _`sec:utilities:processSetsName`:

processSetsName
---------------

**processSetsName** is an extended version of **processSets** where you
can provide name of the input and output files, number of probe fields,
switch to allow moving probes and region name.
Listing `[lis:processSetsName] <#lis:processSetsName>`__ shows
**processSetsName** usage.

.. code:: bash

   $ processSetsName -npf 2 -movingProbe 0 -region "porousMat" "input" "output"

.. _`sec:utilities:tutoInDevelopment`:

tutoInDevelopment
-----------------

**tutoInDevelopment** is used to send an error message and then stop the
run of a tutorial in development. The tutorial will run normally if the
**debug** flag is **yes** allowing the continuation of the development.
Listing `[lis:tutoInDevelopment] <#lis:tutoInDevelopment>`__ shows
**tutoInDevelopment** usage.

.. code:: bash

   $ tutoInDevelopment -debug "no" -errorMsg "This tutorial is in development."

The *tutoInDevel.sh* script was added to **PATH** to simplify the usage
of **tutoInDevelopment** by allowing default arguments.
Listing `[lis:Allrun:utilities:tutoInDevel] <#lis:Allrun:utilities:tutoInDevel>`__
shows how to call the *tutoInDevel.sh* script in the *Allrun* tutorial
file and Listing `[lis:tutoInDevel.sh] <#lis:tutoInDevel.sh>`__ shows
its usage.

.. code:: bash

   cd ${0%/*} || exit 1    # Run from this directory
   eval `tutoInDevel.sh`   # Tutorial in development

.. code:: bash

   $ ./Allrun "no" "This tutorial is in development."

.. _`sec:utilities:patoCodingStyle`:

patoCodingStyle
---------------

Listing `[lis:patoCodingStyle] <#lis:patoCodingStyle>`__ shows how to
format the C++ code in PATO. This utility needs to be run before a
commit.

.. code:: bash

   $ patoCodingStyle -dir "$PATO_DIR" # -format yes -verbose

.. _`sec:utilities:tests`:

tests
-----

**tests** directory contains the testing framework and testing suite.
The unit tests can be run through the **runtests** executable. During
the tests, the outputs from the models and tutorials are compared to
reference files located in **testsuites** directory.
Listing `[lis:runtests] <#lis:runtests>`__ shows **runtests** usage.

.. code:: bash

   $ runtests # -h for help

Listing `[lis:test_example] <#lis:test_example>`__ shows an output
example of successful unit testing (**TestIOFunctions**).

.. code:: bash

   [-- TestIOFunctions -- Test 1 / 4: Success -- ClockTime = 00h00m03s --]
   [-- TestIOFunctions -- Test 2 / 4: Success -- ClockTime = 00h00m03s --]
   [-- TestIOFunctions -- Test 3 / 4: Success -- ClockTime = 00h00m03s --]
   [-- TestIOFunctions -- Test 4 / 4: Success -- ClockTime = 00h00m03s --]