Running multistar#

A typical run may look as follows:

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

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#

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#

property Driver.runtime#

total wallclock time (s)

property Driver.steps#

total number of steps computed

property Driver.evals#

total number of drivative function evaluations

Run API#

Driver.rund(dt=None, dt0=None, dtmin=None, dtmax=None, dtd=None, nstep=None, nsave=None, tsave=None, eps=None, tmax=None, silent=None, flags='run', token=None, cont=None, cutoff=None, interact=None, truncate=True, iext=0, etadelay=None, discard=False, tbegin=None, tend=None, verb=None)#

Fortran dynamic driver

Parameters:

  • dt – total time aiming to run

    if complex, run to imag(dt)

    if negative, run backward in time

  • nstep – maximum number of steps to run

    0 == no limit (default)

  • dtd – minimum time step for recording output

  • dt0 – initial time step.

    Also used as default value for maximum time step.

  • dtmin – minimum time step.

    if 0, set to dt0

    if < 0, set to 1. (FORTRAN DEFAULT)

  • dtmax – maximum time step.

    if 0, set to dt0

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

  • tmax – maximum wallclock runtime (s)

  • 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 (s)

    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)

  • nsave – maximum number of data to save

  • tsave – maximum time to save

  • flags –

    "run"

    continue using same flags (default)

    None

    use default flags (from self._flags)

    int

    use these flags

    TODO

    interpret dict and strings (separate out compile_flags routine)

  • verb – verbise flags for driver

  • TODO –

    • try regroup of Jaccobi coordiates on fail

      ? flip recorded data or track indexing

      ? indexing for star data?

      = this will be generalised for directfp

Driver.runs(dt=None, nstep=None, nsave=None, dt0=None, dtmin=None, dtmax=None, eps=None, tmax=None, silent=None, token=None, flags='run', cont=None, cutoff=None, interact=None, etadelay=None, discard=False, tbegin=None, tend=None, verb=None)#

Fortran step driver

Parameters:

  • tmax – maximum wallclock runtime (s)

  • cont –

    False

    run from start

    True

    ontinue, keep data

    Ellipis

    continue, discard data

    real value

    continue form that time, keep data

    imag value

    continue form that time, discard data

  • discard –

    Ellipsis

    discard initial data when continuing

    True

    discard all data but the last point

    implies nsave = 1

    False

    do nothing (default)

  • flags –

    "run"

    to continue using same flags

    None

    use default flags (from self._flags)

    int

    use these flags

TODO - Documnetaion incomplete.

Flags#

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

Current flags#

property Driver.flags#

current flags as string

Driver.get_flags(numeric=False)#
Driver.set_flags(flags=None, /, silent=None, return_old_flags=True, **kwargs)#

set run flags, returns old flags

Driver.get_flag(flag)#
Driver.get_flag_bit(bit)#
Driver.set_flag(flag=None, /, silent=None, value=True, **kwargs)#
Driver.unset_flag(*args, **kwargs)#

Flags of last run#

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

property Driver.run_flags#

current run flags as string

Driver.get_run_flags(numeric=False)#
Driver.get_run_flag(flag)#
Driver.get_run_flag_bit(bit)#

Metaflags#

Access to historic switches and meta flags.

Currently, GR is the only such flag.

Driver.get_meta_flag(flag)#
Driver.get_run_meta_flag(flag)#
TODO

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

TODO

re-design ‘flags’ interface, make self-contained object