.. _ids-manual:

IDS manual
-----------

.. program:: mole

::

	ids <subcommand> [options]

Subcommands:

.. describe:: init
	
	:ref:`Initialize the ids environment including example configuration files <ids-cmd-init>`

.. describe:: go

	:ref:`Run the optimization <ids-cmd-go>`

.. describe:: harvest

	:ref:`Harvest all inversion results (needed to create report) <ids-cmd-harvest>`

.. describe:: report

	:ref:`Create inversion result report <ids-cmd-report>`

To get further help and a list of available options for any subcommand run::

    ids <subcommand> --help


Subcommands and options
^^^^^^^^^^^^^^^^^^^^^^^

Each subcommand has its own set of options. Use ``ids <subcommand> --help`` to
see which of the following options apply to any of the subcommands listed
above.

.. _ids-cmd-init:

init
""""

.. option:: rundir

	Name of the IDS run directory structure. Must be given.

.. option::    --force

		If given, a previously existing IDS run directory structure with the same name will
		be overwritten (including data and configuration files).

.. _ids-cmd-go:

go
"""

.. option:: config

	Path to the IDS config file which defines the inversion parameters. Must be
	given.

.. option::    --force

		If given, a previously existing run with the same name will
		be overwritten.

.. _ids-cmd-harvest:

harvest
"""""""
.. option:: rundir

	Path to the run directory, for which results shall be harvested. Must be
	given.

.. option::    --force

		If given, any previously harvested results are overwritten.

.. _ids-cmd-report:

report
""""""
.. option:: rundir

	Path to the run directory, for which report plots shall be generated. Must
	be given.

.. option::    --nparallel

		Number of processes run in parallel. `0` allows for using all cores.


Command line examples
---------------------

Initialize an IDS environment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Initialize a new IDS runing folder called ``ids_directory``.

.. code-block:: bash

    ids init ids_directory


The option ``--force`` will clear any previous IDS environment with the same
name and initialize a new clear one.


Run an IDS estimate
^^^^^^^^^^^^^^^^^^^

Run the optimization for the given event using a configuration file stored in `config/idsconfig_example.conf`.

.. code-block:: bash

	ids go config/idsconfig_example.conf

The option ``--force`` will clear any previous IDS run with the same run name as defined in the configuration file.


Create an IDS report
^^^^^^^^^^^^^^^^^^^^

Generate plots of the results of a run called `run/ids_testrun`.

.. code-block:: bash

	ids report run/ids_testrun/

The option ``--force`` will clear any previous IDS run with the same run name as defined in the configuration file.