Getting Started

This page assumes you have already installed slim and its dependencies. If you haven’t please check the README.

Run the simulator

The easiest way to run SLIM is via the command line.

The main script you’ll need to run is SeaLiceMgmt. The general way to launch it is the following:

python -m slim.SeaLiceMgmt output_folder/simulation_name simulation_params_directory

For example:

python -m slim.SeaLiceMgmt output/Loch_Fyne config_data/Fyne

The entry point of this program is the slim.Simulator.Simulator class.

All you have to do is to instantiate an object of that class and provide a slim.Config.Config instance. For example:

from slim.simulation.config import Config
from slim.simulation.Simulator import Simulator

cfg = Config("config_data/config.json", "config_data/Fyne")
sim = Simulator("output", "Fyne_foobar", cfg)
sim.run_model()

Runtime Environment

An environmental setup consists of a subfolder containing three files:

params.json with simulation parameters specific to the organisation;
interfarm_time.csv with travel time of sea lice between any two given farms (as a dense CSV matrix);
interfarm_prob.csv with probability of sea lice travel between any two given farms (as a dense CSV matrix);

Optionally, an environment may contain a CSV report (called report.csv) of real-world lice counts and actions. If present, they will be imported by the GUI. To see how to generate those reports, check slim/surveys/scraper.py.

See config_data/Fyne for examples.

Additionally, global simulation constants are provided inside config_data/config.json.

Warning

Do not change the values inside config.json! Here are two reasons:

changing those values will impact any simulation;
those values are determined via experimentation and fitting on real world data.

Currently, the only way to overwrite these parameters is via manual overriding, for example as described in Parameter Override.

Advanced features

Parameter Override

If one wishes to modify a runtime option without modifying those files an extra CLI parameter can be passed to the command. In general, for each key in the format a_b_c an automatic parameter in the format --a-b-c will be generated. For example:

python -m slim.SeaLiceMgmt out/0 config_data/Fyne --seed=0 --genetic-mechanism=discrete

For now, nested and list properties are not yet supported.

slim.Config.Config allows you to override the default parameter configuration of either global or environment-specific variables, assuming there is no name clash.

For example:

override = {
    "seed": 42,
    "gain_per_kg": 5.0,
    "dam_unavailability": 3,
    "start_date": "2017-10-01 00:00:00",
    "end_date": "2019-10-01 00:00:00",
}
cfg = Config("config_data/config.json", "config_data/Fyne")
sim = Simulator("output", "Fyne_foobar", cfg)
sim.run_model()

Note

The format of the override options must be consistent with the schema. This also means that overriding with the schema. See config_data/config.schema.json and config_data/params.schema.json.

Artifact Saving

By default, SLIM generates some artifacts ready to be digested by our visualiser or by any custom pipeline.

There are two possible types of artifacts:

output logs, saved as simulation_data_${NAME}.pickle.lz4.
serialised internal states (also known as dump ), saved as checkpoint_${NAME}.pickle.lz4.

In the majority of cases, you do not need to care about dumping and will probably stop reading now.

Thanks to multiprocessing, artifacts are saved by a separate process from the main simulation, therefore no slow-down should occur. Therefore, it is safe to let it on (default). To change the frequency of writing one can pass --save-rate=N to the wished frequency (or 0 to disable altogether).

This is a LZ4-compressed series of self-describing Python dictionaries. We provide an extractor for these in slim.simulator.load_artifact().

The second is available for debugging purposes and has been historically used as our main artifact.

Note

Dumping is not available in multiprocessing mode.

To generate a dump every n days add the --checkpoint-rate=n option. For example:

python -m slim.SeaLiceMgmt outputs/sim_1 config_data/Fyne --checkpoint-rate=1"

This will save the output every day.

To resume a session one can instead pass the –resume parameter. Via CLI:

python -m slim.SeaLiceMgmt outputs/sim_1 config_data/Fyne --resume="2017-12-05 00:00:00"

If you only know n days have elapsed since the start use the –resume-after=n option. For example:

python -m slim.SeaLiceMgmt outputs/sim_1 config_data/Fyne --resume-after=365

To generate a dump every n days set up an instance of slim.Config.Config and pass the extra parameter checkpoint_rate. The rest follows as usual.

from slim.simulation.Config import Config
from slim.simulation.Simulator import Simulator

n = 10 # every 10 days

cfg = Config("config_data/config.json", "config_data/Fyne", checkpoint_rate=n)
sim = Simulator("output", "Fyne_foobar", cfg)
sim.run_model()

# Press Ctrl+C before the end to stop it prematurely

To resume the session you need to know either a timestamp or the number of elapsed days.

from slim.simulation.config import Config, to_dt
from slim.simulation.simulator import reload

timestamp = to_dt("2018-12-05 00:00:00")
sim = reload("output", "Fyne_foobar", timestamp=timestamp)
# or alternatively
# sim = reload("output", "Fyne_foobar", resume_after=365)
# Occasionally add breakpoints wherever you wish
sim.run_model()

Additionally, one can override the config parameters.

Note

Dumps are opened in read-only mode when resuming. It is not allowed to combine resuming and dumping/artifact saving.

Multiprocessing

Note

The support for multiprocessing is still experimental. Head to Multiprocessing on farms for details.

To enable multiprocessing, you need to know how many farms you are going to simulate and how much parallelism you wish to achieve. For example, if simulating an environment with 8 agents in an octa-core system, it is stafe to allocate one farm per process. Therefore, you can pass the --farms-per-process=1 option. The lower is better (if your system supports it) but 0 (the default) enables single-process mode.

Run the GUI

We also provide a GUI for debugging and visualisation. Its support is still heavily experimental so please use with caution.

To run the GUI you need to launch slim.SeaLiceMgmtGUI, for example via: `python -m slim.SeaLiceMgmtGUI` and provide your artifact data.

Warning

Do not try to parse a dump. While this has historically been the case, it will no longer work.