xsimlab.Model.execute

Model.execute(stage, runtime_context, hooks=None, validate=False, parallel=False, scheduler=None)

Run one stage of a simulation.

Parameters

  • stage ({'initialize', 'run_step', 'finalize_step', 'finalize'}) – Name of the simulation stage.

  • runtime_context (dict) – Dictionary containing runtime variables (e.g., time step duration, current step).

  • hooks (dict, optional) – Runtime hook callables, grouped by simulation stage, level and trigger pre/post.

  • validate (bool, optional) – If True, run the variable validators in the corresponding processes after a process (maybe) sets values through its foreign variables (default: False). This is useful for debugging but it may significantly impact performance.

  • parallel (bool, optional) – If True, run the simulation stage in parallel using Dask (default: False).

  • scheduler (str, optional) – Dask’s scheduler used to run the stage in parallel (Dask’s threads scheduler is used as failback).

Returns

signal – Signal with hightest priority among all signals returned by hook functions and/or process runtime methods, if any. Otherwise, returns RuntimeSignal.NONE.

Return type

RuntimeSignal

Notes

Even when run in parallel, xarray-simlab ensures that processes will not be executed before their dependent processes. However, race conditions or perfomance issues may still occur under certain circumstances that require extra care. In particular:

  • The gain in perfomance when running the processes in parallel highly depends on the graph structure. It might not be worth the extra complexity and overhead.

  • If a multi-threaded scheduler is used, then the code implemented in the process classes must be thread-safe. Also, it should release the Python Global Interpreted Lock (GIL) as much as possible in order to see a gain in performance.

  • Multi-process or distributed schedulers may have very poor performance, especially when a lot of data (model state) is shared between the model processes. The way xarray-simlab scatters/gathers this data between the scheduler and the workers is not optimized at all. Addtionally, those schedulers may not work well with the given hooks and/or when the processes runtime methods rely on instance attributes that are not explicitly declared as model variables.