Running `multistar`
===================

A typical run may look as follows:

.. code-block:: python

   from multistar import multi as M
   from physconst import YR
   m = M('-eight')
   m.rund(1*YR)
   m.plot3()

.. _rund:

rund
----

dynamic (time step) drive

Arguments
^^^^^^^^^

dt
   total time to run (seconds)

   If not set, it can be computed from (tbegin, and) tend

Optional arguments
^^^^^^^^^^^^^^^^^^

nstep
   maximum number of steps to run

   0
      no limit (default)

dtd
   minimum time step for recording output (s)

tsave
   maximum time to save (discard older)


truncate
   True
      last time step of run is truncated to requested dt (default)

   False
      code will stop when time >= dt is reached.

.. _runs:

runs
----

step driver (fixed time step of output, may still do sub-cycling)


Arguments
^^^^^^^^^

dt
   steps size (seconds)

   if not set, it can be set from (tbegin,) tend, and nstep

nstep
   number of steps (default: 1000)


Common parameters
-----------------

tmax
   maximum wallclock runtime (s)


nsave
   maximum number of data to save (discard older)

cont
   False
      run from start

   True
      continue, keep data

   Ellipis
      continue, discard old data

   None
      (default)

      True
         if model was run before,

      False
         otherwise

   <number>
      time from which to start

      (discard old data if an imaginary number is used)

discard:
   Ellipsis
      discard initial data when continuing

   True
      discard all data but the last point

      implies nsave = 1

   False
      keep data (default)


dt0
   initial time step (s).

   default for maximum time step.


dtmin
   minimum time step (s).

   0
      set to dt0

   < 0
      set to 1. (FORTRAN DEFAULT)

dtmax
   maximum time step (s).

   0
      set to dt0

   < 0
      set to infinity (1.e99, FORTRAN DEFAULT)

flags
   'run'
      to continue using same flags

   None
      use default flags (from self._flags)

   <int>
      use these flags

eps
   convergence accuracy

   current default is 1e-13

token
   set some run identifier (used by genetic code)

cutoff
   set cutoff matrix for Jacobi coordinates

interact
   set object interaction matrix

etadelay
   time between ETA outputs (default 10 s)

tbegin
   start time of simulation (s)

   This is use for sync with star data file

tend
   end time of simulation (s)

silent
   set verbosity.  (default: `self.silent` set on object generation,
   with default `None`)

verb
   binary verbosity flags (bits) for Fortran driver

   bit constants are defined in module ``multistar.constants``

   =============== === ===========
   constant        bit description
   =============== === ===========
   IVERB_INTERACT  0   interact
   IVERB_DRIVER    1   driver
   IVERB_INTEGRATE 2   integrate
   IVERB_ETA       3   eta
   =============== === ===========

   Default is to disable all flags if ``silent`` is ``True`` and to
   enable all flags if ``silent`` is ``False`` or ``None``.  Bits need
   to be added as `2**bit`.

   In module ``multistar.constants``, the following values are defined

   =============== ==================
   constant        value
   =============== ==================
   VERB_INTERACT   2\**IVERB_INTERACT
   VERB_DRIVER     2\**IVERB_DRIVER
   VERB_INTEGRATE  2\**IVERB_INTEGRATE
   VERB_ETA        2\**IVERB_ETA

   VERB_ALL        -1
   VERB_NONE        0
   =============== ==================


Run statistics
--------------

.. module:: multistar.base
   :no-index:

.. autoproperty:: Driver.runtime

.. autoproperty:: Driver.steps

.. autoproperty:: Driver.evals

Run API
-------

.. automethod:: multistar.driver.Driver.rund

.. automethod:: multistar.driver.Driver.runs

Flags
-----

Flags are internally represented as bit field represented in (64 bit)
integer number.  The ``Driver`` module provides a user-friendly
interface.

Current flags
^^^^^^^^^^^^^

.. autoproperty:: multistar.driver.Driver.flags

.. automethod:: multistar.driver.Driver.get_flags

.. automethod:: multistar.driver.Driver.set_flags

.. automethod:: multistar.driver.Driver.get_flag

.. automethod:: multistar.driver.Driver.get_flag_bit

.. automethod:: multistar.driver.Driver.set_flag

.. automethod:: multistar.driver.Driver.unset_flag

Flags of last run
^^^^^^^^^^^^^^^^^

For flags used in recent run (what should be used in analysis
routines):

.. autoproperty:: multistar.driver.Driver.run_flags

.. automethod:: multistar.driver.Driver.get_run_flags

.. automethod:: multistar.driver.Driver.get_run_flag

.. automethod:: multistar.driver.Driver.get_run_flag_bit

Metaflags
^^^^^^^^^

Access to *historic* switches and *meta* flags.

Currently, ``GR`` is the only such flag.


.. automethod:: multistar.driver.Driver.get_meta_flag

.. automethod:: multistar.driver.Driver.get_run_meta_flag


TODO
   add more generating runs form exciting, continuing, and routines
   for this



TODO
   re-design 'flags' interface, make self-contained object