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 multistar.grid framework.

Grid framework#

The basic setup is done in a class derived from

class multistar.grid.base.SystemBase(toml=None)#

Bases: Task

process_model(model, dtx, **kwargs)#: return modified model (or original), whether finished or outcome (implies finished)

loop(**kwargs)#

dt: (rund): total time to run loop for defaults to self.dt, m.toml.tend, (infty if tmax > 0 or 1000, otherwise)
dt: (runs): step size (requied), defaults to m.dt
tx: (rund): loop over total execution time in units of tx defaults to dt
nstep:: total number of steps to run
nstepx: (runs): loop over total execution steps (nstep) in units of nstepx
nstepx: (rund): to limit data size of rund, add limit on number of steps per cycle

that we will refer to as class System.

from multistar.grid import SystemBase

class System(SystemBase):
    ...

Simulation template#

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

Simulation parameters#

The setup is configured in the setup method.

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 Fate class

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 analyze method.

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

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

class Outcome(DataOutcome):
    fate = Fate

Cartesian grids#

In order to run multiple “systems” (class System) we define a Study class derived from

class multistar.grid.base.StudyBase(**kwargs)#

Bases: QueueProcessor

VERSION = 10200#: Interface for parallel execution of runs

config(index: int) → Config#

configuration of result at a given index in results array

Parameters:: index – 0-based index of run
Returns:: (generated) configuration that was used by the run

model(index: int) → SetupBase#

multistar model with configuration of result at a given index in results array

Parameters:: index – 0-based index of run
Returns:: multistar model with (generated) configuration that was used by the run

Note

This is the same as M(s.config(i))

hist(vars=None, data=None, parm=Ellipsis, filter=None, xlog=None, ylog=None, zlog=None, bins=None, cmap=None, mode='hex', xlim=None, ylim=None, zlim=None, barfrac=1, dlog=None, dsig=True, dgam=2.2, dfac=1, dlim=None, select=None, exclude=None, percentage=False, stat='pie', stat_num=False, stat_order=None, label=Ellipsis, weighted=None, weights_select=None, weights_exclude=None)#

Parameters:: vars – "fate" makes pie chart

M(index=0, **kwargs)#

return multistar run setup from result with that (filtered) index

See _filtered_results documentaion for filter options.

from multistar.grid import StudyBase

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

Grid parallelisation#

The grids are run in parallel using the multistar.parallel framework.

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

parallel.set_parallel()#

Set parallel mode

Currently mode may be one of

queue, process: individual processes connected by queues (default)
pool: parallelisation using process pools
serial, single, debug: serial execution, good for development and debugging
db: cline/server mode using a database (sqlite3)

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#

Distribution functions library, with emphasis on rotations

The functions use require passing of a (pseudo-)randim number generator, rng. This can be generated using

rng = np.random.default_rng(SEED)

Where SEED is a seed value for the generator to allow reproducible results. SEED may be omitted.

class multistar.grid.distributions.Sample#

Bases: object

Base class for sampling

class multistar.grid.distributions.Const(val=1)#