Usage#

Generating multistar objects#

multistar.multi(*args, **kwargs)#

Generate multistar object from configuration file.

The general function to set up simulation runs.

Parameters:

  • args[0], data (str | dict | multistar) – File name or data. data can be string to parse or toml object.

  • type | setup – Type of setup. If not provided, is read from data

  • full (bool) – Whether to use full or hierarchical codes. Default False

  • hierarchical (bool) – opposite of full

  • secular (bool) – Whether to use secular code. Default False. Currently only supported by two-object setup.

  • direct (bool) – Opposite of secular

  • mode (str) – Can be “secular” or “direct”

  • silent (bool) – Less verbose output (default: None, becomes False in most subroutines)

    May also be set to “ALL” to disable warnngs by default.

  • warn (bool) – Print warnings (default: None, which implies True in Setup.)

  • verbose (str | int) – passed to load function in case a multistar object is loaded from file.

Returns:

multistar (object) – multistar object of requested type or None if it fails.

Notes

relative path input options according to multistar.config.expandpath()

multistar.config.expandpath(path)#

Expand search paths for toml files.

Parameters:

path (str | pathlib.Path) – path to process

Notes

MULTISTARDATAPATH :

environment variable for user paths

filename initial token:

^

look in examples then in user path

&

look in user path then examples

+

look only in user path

-

look only in examples

%

look relative to multistar module directory

The .toml extension is added automatically if missing.

Example#

from multistar import multi as M
m = M('-eight')
multistar.load(filename, *args, path=None, verbose='INFO', **kwargs)#

Generic loader function.

If filename is a simulation data object, just return that object.

If the filename has the extension .toml the config file is loaded and passed to multi for loading.

Otherwise, load filename from disk and unpickle it.

Parameters:

  • filename (str | pathlib.Path | object) – name of file to load

  • path (str | pathlib.Path) – optional path of file to load

  • verbose (str | int) – verbosity level, taken from logging

    Logging levels are
    0

    NOTSET

    10

    DEBUG

    20

    INFO

    30

    WARNING

    40

    ERROR

    50

    CRITICAL

  • *args – additional arguments passed to toml file generation

  • **args – additional keyword arguments to toml file generation

Returns:

object – Object loaded from disc or generated multistar object.

Driver.save(filename: str | Path)#

Save multistar object to file using pickle.

Parameters:

filename (str | pathlib.Path) – filename to write to

Notes

The file is compressed if one of the following extensions is used:

  • .gz

  • .bz | .bz2

  • .xz

  • .zst (Python 3.14+)

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 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 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 (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.