.. _basic_cli:

Execution Procedures
####################

Overview
========

Matmodlab is executed by running the ``mml`` procedure.  Several parameters can be set either on the command line or in an environment file (see :ref:`basic_config`).

mml Summary
===========

::

   mml [-h|help] <command> [<args>]

mml Commands
------------

(empty)
.......

Launch the (empty) matmodlab gui

build
.....

Build fortran libraries

Optional build arguments
~~~~~~~~~~~~~~~~~~~~~~~~

::

  -h, --help    show this help message and exit
  -v V          Verbosity
  -w            Wipe before building
  -W            Wipe and exit
  -m M [M ...]  Materials to build
  -u            Build auxiliary support files only

clean
.....

Remove files generated by matmodlab (.pyc, .o, .so, .a, build, etc.)


run
...

Run a matmodlab simulation script in the matmodlab environment.

Required run arguments
~~~~~~~~~~~~~~~~~~~~~~

::

  source                Python source file

Optional run arguments
~~~~~~~~~~~~~~~~~~~~~~

::

  -h, --help            show this help message and exit
  -v V                  Verbosity
  --debug               Debug mode
  --sqa                 SQA mode
  --switch MATX MATY    Run with MATY instead of MATX, if present(not
                        supported by all models)
  -B MATERIAL           Wipe and rebuild MATERIAL before running
  -V                    Launch results viewer on completion
  -j NPROCS, --nprocs NPROCS
                        Number of simultaneous jobs
  -W {std,all,error}    Warning level
  -w                    Wipe and rebuild material in Material factory before
                        running

test
....

``mml test`` is merely a wrapper around ``py.test``

view
....

Launch the matmodlab viewer

Required view arguments
~~~~~~~~~~~~~~~~~~~~~~~

::

  sources               Output database file[s]


.. _exodiff:

Other Command Line Tools
========================

exodiff
-------

Compare ExodusII database files::

  usage: exodiff [-h] [-f F] [--interp] source1 source2

  positional arguments:
    source1
    source2

  optional arguments:
    -h, --help  show this help message and exit
    -f F        Use the given file to specify the variables to be considered and
                to what tolerances
    --interp    Interpolate variabes through time to compute error

Exodiff Tolerance File
......................

By default, ``exodiff`` compares all common variables in database files
``source1`` and ``source2`` and uses standard tolerances to determine if the
files are the same. Optionally, a "diff" file can be sent to ``exodiff`` (the
``-f``) to fine tune variables to be compared and tolerances. The diff file is
an xml file whose root element must be ``ExDiff``. The only recognized child
of ``ExDiff`` is ``Variable``. If a diff file is specified, only those
variables specified are compared.

Both ``ExDiff`` and ``Variable`` may define ``ftol`` and ``dtol`` attributes
to specify failure and differencing tolerances. Tolerances defined in
``ExDiff`` apply to all variables. Tolerances defined by a ``Variable`` apply
only to that variable (regardless of tolerances defined in ``ExDiff``).

``Variable`` must define the ``name`` attribute to specify the name of the
variable in the database file.

Example
~~~~~~~

Consider the following diff file::

  cat exodiff_spec.xml

  <ExDiff ftol="1e-6" dtol="1e-8">
    <Variable name="STRAIN_XX" ftol="1.e-4" dtol="1.e-6"/>
    <Variable name="STRAIN_YY" ftol="1.e-4" dtol="1.e-6"/>
    <Variable name="STRAIN_ZZ" ftol="1.e-4" dtol="1.e-6"/>
    <Variable name="STRESS_XX"/>
    <Variable name="STRESS_YY"/>
    <Variable name="STRESS_ZZ"/>
    <Variable name="PRESSURE" ftol="1.e-1" dtol="5.e-2"/>
  </ExDiff>

exodump
-------

Dump information from ExodusII database::

  usage: exodump [-h] [-o O] [--list] [--ffmt FFMT]
                 [--ofmt {mathematica,ascii,ndarray}] [--step STEP]
                 [--block BLOCK] [--element ELEMENT]
                 source [variables [variables ...]]

  positional arguments:
    source
    variables             Variables to dump

  optional arguments:
    -h, --help            show this help message and exit
    -o O                  Output file name
    --list                List variable names and exit
    --ffmt FFMT           Output floating point format
    --ofmt {mathematica,ascii,ndarray}
                          Output format
    --step STEP           Step
    --block BLOCK         Block number
    --element ELEMENT     Element number