Usage
=====

Generating `multistar` objects
------------------------------

.. module:: multistar

.. autofunction:: multi

.. autofunction:: multistar.config.expandpath

Example
^^^^^^^

::

   from multistar import multi as M
   m = M('-eight')


.. autofunction:: load


.. module:: multistar.driver

.. automethod:: Driver.save

Example
^^^^^^^
::

   from multistar import multi as M
   from physconst import YR
   m = M('-eight')
   m.rund(1000*YR)
   m.save('~/eight.xz')

::

   from multistar import load as L
   from physconst import YR
   m = L('~/eight.xz')
   m.plot3(trail=0.25*YR)


Overwriting config values on generation
---------------------------------------

Rather than modifying the TOML file for each setup in case studies,
they can be used as templates and updated on generation of the
``multistar`` object.  This is done suing the ``update`` keyword and
passing a dictionary with the fully qualified key names and values.

See the :ref:`Config API <config_api>` for details on key names.

Example
^^^^^^^
::

   from multistar import multi as M
   m = M('-DI_Herculis', update={'orbit.en' : 0.5, 'orbit.an_AU' : 0.2})


Advanced modification of configurations
---------------------------------------

For more sophisticated modifications, e.g., multiplying values by some
factor, one needs to load the config file, modify it, and then use
this modified version to set up ``multistar``.

See the :ref:`Config API <config_api>` for details on modifying
configurations.


Example
^^^^^^^
::

   from multistar import multi as M
   from multistar.config import Config as C
   c = C('-DI_Herculis')
   c1 = c.copy()
   c1['orbit.en'] *= 1.0001
   c2 = c.copy()
   c2['orbit.en'] *= 0.9999
   m1 = M(c1)
   m2 = M(c2)
   m1.rund(tmax=1)
   m2.rund(tmax=1)



Environment Variables
=====================

`multistar` build
-----------------

MULTISTARDATAPATH
   environment variable for path(s) to user `.toml`
   config files used for ``+``, ``&``, ``^`` `toml` filename initial
   tokens (:py:func:`multistar.config.expandpath`)


MULTISTAR_UPDATE
   determine whether to recompile the Fortran code

   `1`, `TRUE`, `T`, `YES`, `Y`
      recompile when change is detected **(default)**

   `0`, `FALSE`, `F`, `NO`, `N`
      do not check for re-compile


MULTISTAR_NEW
   set up `meson` build directory for library from scratch every time
   code is built.

   `1`, `TRUE`, `T`, `YES`, `Y`
      create build from scratch **(default)**

   `0`, `FALSE`, `F`, `NO`, `N`
      continue using existing build directory

   .. note::
      Switching off recreation can speed up compilation a bit and also
      reduce amount of compile output to code that has changed.  This
      is useful for debugging.  But be aware that other changes, e.g.,
      switch to/from `debug` mode will not be reflected in the build.

      TODO: Use `meson` to check build type and ignore setting if
      release type does not match or there is compiler mismatch.


MULTISTAR_DEBUG
   set debug mode

   `1`, `TRUE`, `T`, `YES`, `Y`
      *enable* debug build and outputs

   `0`, `FALSE`, `F`, `NO`, `N`
      *disable* debug build and outputs **(default)**

      Make `release` build instead


Grid parallel processing
------------------------

MULTISTAR_PARALLEL_MODE
   Determine what parallelisation method to use

   `queue`
      use python processing and communicate via queues **(default)**

   `pool`
      use python processor pools for parallel processing

   `serial`
      run in serial mode, good for debugging

   `single`
      same as `serial`

   `debug`
      same as `serial`

   `db`
      use database server (implementation in revision)



MULTISTAR_PARALLEL_STARTMETHOD
   Set process start method for parallel processing.

   Possible values are `'fork'`, `'spawn'`, `'forkserver'` if allowed
   on your platform.  See Python mulitprocessing documentation.