Grid
====

The only practical way to set up and configure extended is to write a
set of classes in your own project module, using classes derived from
base classes of the :code:`multistar.grid` framework.

Grid framework
--------------

The basic setup is done in a class derived from

.. autoclass:: multistar.grid.base.SystemBase

that we will refer to as class :code:`System`.

.. code-block:: python

   from multistar.grid import SystemBase

   class System(SystemBase):
       ...


Simulation template
...................

.. code-block:: python

    _toml = '/path/to/my/template.toml'

Simulation parameters
.....................

The setup is configured in the :code:`setup` method.

.. code-block:: python

    def setup(
            self, *,
            P=1, Q=1, ...,
            **kwargs,
            ):

        super().setup(**kwargs)

	...

Outcomes of simulations
.......................

Usually, we are interested ion the fate of a system.  To encode the
specific fates of a project, along with some properties for labelling
and colouring them, we define a :code:`Fate` class

.. code-block:: python

   class Fate(FateBase):
       ANY       = FateBase.ANY
       FAIL      = FateBase.FAIL
       STABLE    = FateBase.STABLE
       UNKNOWN   = FateBase.UNKNOWN
       MYOUTCOME = 10
       ...

       labels = {
           FAIL:      'fail',
           STABLE:    'stable',
           UNKNOWN:   'unknown',
           MYOUTCOME: 'my outcome',
           ...
	   }

   # generate keys

   keys = {v:k for k,v in labels.items()}

   colors = {
       FAIL :     rgb([1.0, 1.0, 1.0]),
       STABLE:    rgb([0.0, 0.0, 0.0]),
       UNKNOWN:   rgb([0.7, 0.7, 0.7]),
       MYOUTCOME: rgb([1.0, 0.0, 0.0]),
       ...
       }

   # some checks

   assert np.all(np.array(list(colors.keys())) >= 0)

   # an array for easy indexing

   colarr = np.zeros((np.max(list(colors.keys()))+1, 3))
   for i,v in colors.items():
       colarr[i,:] = v

TODO - why are these transforms not part of an __init__ or metaclass?

The results are analyzed in the :code:`analyze` method.

.. code-block:: python

   def analyze(self, m, dt, fail=True):
       ...

The :code:`analyze` method should return an :code:`Outcome` object
derived from `multistar.grid.base.DataOutcome` that set the
:code:`Fate` class for the project, usually all you need is

.. code-block:: python

   class Outcome(DataOutcome):
       fate = Fate


Cartesian grids
---------------

In order to run multiple "systems" (class :code:`System`) we define a
:code:`Study` class derived from

.. autoclass:: multistar.grid.base.StudyBase

.. code-block:: python

   from multistar.grid import StudyBase

   class Study(StudyBase):
       task = System
       fate = Fate


Grid parallelisation
--------------------

The grids are run in parallel using the :code:`multistar.parallel`
framework.

To set the method use, set the parallelisation method before importing
the grid routines or derived classes:

.. automethod:: multistar.parallel.set_parallel

This is a bit of a patchwork, depending on this setting, the grid
routines will be derived from different 'backend' classes.


Parallelisation models
......................

Processes
^^^^^^^^^

Process pools
^^^^^^^^^^^^^

Serial
^^^^^^

for debugging

Client/server (database)
^^^^^^^^^^^^^^^^^^^^^^^^

TODO - one could also use database for parallel/serial mode.  This
could replace current framework for "batches."

General parameters
..................

timeout
   maximum time (s) for individual results

endtime
   maximum runtime (s) for grid

   This can be useful for running in job queues on clusters or HPC
   machines to terminate a run (and save results) before the maximum
   (requested or mandated) job runtime is exceeded and all results
   would be lost.

   You may also consider to use fragments.

nparallel
   number of parallel jobs


Monte Carlo
-----------

Distribution functions
----------------------

.. automodule:: multistar.grid.distributions

Standard plots
--------------

Slices (regular grids)
......................

.. automethod:: multistar.grid.base.StudyBase.plot

Projections (irregular samples)
...............................

.. automethod:: multistar.grid.base.StudyBase.project

Statistical information (all grids)
...................................

.. automethod:: multistar.grid.base.StudyBase.hist
   :no-index: