duat.run

Run configuration files with OSIRIS.

class duat.run.Run(run_dir)[source]

An osiris run.

run_dir

str – Directory where the run takes place.

total_steps

int – Amount of time steps in the simulation.

running_mode

str – Can be “local” if a local process was found, “grid” if a grid job was found, or “” otherwise. A simulation launch in the grid but running in the local machine will be tagged as “local” (since you can access its process).

processes

list of psutil.Process – If running_mode is “local”, representation of the processes running the simulation.

job

dict – If running_mode is “grid”, information about the job of the simulation.

__init__(run_dir)[source]

Create a Run instance.

Parameters:run_dir (str) – Path where the OSIRIS run takes place. An os-stdin file must exist there.
Raises:FileNotFoundError – If no os-stdin is found.
__repr__()[source]

Return repr(self).

current_step()[source]

Find the current simulation step.

Returns:The simulation step or -1 if it could not be found.
Return type:int
estimated_time()[source]

Estimated time to end the simulation in seconds.

The estimation uses a linear model and considers initialization negligible. For local runs, the start time of a process is used in the calculation. For grid runs, the start time of the job is used instead.

If the run was resumed, the estimation will be wrong.

Returns:The estimation of the time to end the simulation or NaN if no estimation could be done.
Return type:float
get_config()[source]

Return a ConfigFile instance parsing the os-stdin file

get_diagnostic_list()[source]

Create a list with the diagnostic found in the given Run.

Returns:List of the diagnostic found.
Return type:list of Diagnostic
get_size()[source]

Get the size of all run data in bytes.

get_status()[source]

Return the status of the run.

Returns:The status of the run. Possible values are:
  • ”RUNNING”: Either a process is running the simulation (running_mode=”local”) or a qstat job was found (running_mode=”grid”).
  • ”FAILED”: An error was detected in the OSIRIS output.
  • ”FINISHED”: The simulation has successfully finished its execution.
  • ”INCOMPLETE”: The simulation appears to have started but not running now. You should check the output to try to understand what happened. If restart information was sent, you might want to run “continue.sh” to resume the simulation.
  • ”NOT STARTED”: The files were created, but the simulation is not running. Note you will see this state if the Run is queued in a MPCaller instance.
Return type:str
kill()[source]

Abruptly terminate the OSIRIS processes (if running).

The terminate() method should be used instead to perform a cleaner exit.

If runnning is “local”, sends SIGKILL to the processes. If “grid”, calls qdel.

Raises:subprocess.CalledProcessError – If using a grid and qdel fails.
real_time()[source]

Find the total time in seconds taken by the simulation if it has finished, otherwise returning nan.

terminate()[source]

Terminate the OSIRIS processes (if running).

If runnning is “local”, sends SIGINT to the processes. If “grid”, calls qdel.

Raises:subprocess.CalledProcessError – If using a grid and qdel fails.
duat.run.open_run_list(base_path, filter=None)[source]

Create a Run instance for each of the subdirectories in the given path.

Parameters:
  • base_path (str) – Path where the runs are found.
  • filter (str) – Filter the directories using a UNIX-like pattern.
Returns:

A list with the Run instances, ordered so their paths are in human order.
Return type:

list of Run
duat.run.osiris_1d = ''

str – Path to the osiris-1D.e file

duat.run.osiris_2d = ''

str – Path to the osiris-2D.e file

duat.run.osiris_3d = ''

str – Path to the osiris-3D.e file

duat.run.run_config(config, run_dir, prefix=None, clean_dir=True, blocking=None, force=None, mpcaller=None, create_only=False)[source]

Initiate a OSIRIS run from a config instance.

Parameters:
  • config (ConfigFile) – The instance describing the configuration file.
  • run_dir (str) – Folder where the run is carried.
  • prefix (str) – A prefix to run the command. If None, “mpirun -np X ” will be used when a config with multiple nodes is provided.
  • clean_dir (bool) – Whether to remove the files in the directory before execution.
  • blocking (bool) – Whether to wait for the run to finish.
  • force (str) – Set what to do if a running executable is found in the directory. Set to “ignore” to launch anyway, possibly resulting in multiple instances running simultaneously; set to “kill” to terminate the existing processes.
  • mpcaller (MPCaller) – An instance controlling multithreaded calls. If supplied, all calls will be handled by this instance and the blocking parameter will be ignored.
  • create_only (bool) – Whether just to create the files, but not starting the run.
Returns:

A Run instance describing the execution.
Return type:

tuple
duat.run.run_config_grid(config, run_dir, prefix=None, run_name='osiris_run', remote_dir=None, clean_dir=True, prolog='', epilog='', create_only=False)[source]

Queue a OSIRIS run in a compatible grid (e.g., Sun Grid Engine).

Parameters:
  • config (ConfigFile) – The instance describing the configuration file.
  • run_dir (str) – Folder where the run will be carried.
  • prefix (str) – A prefix to run the command. If None, “mpirun -np X ” will be used when a config with multiple nodes is provided.
  • run_name (str) – Name of the job in the engine.
  • remote_dir (str) – If provided, a remote directory where the run will be carried, which might be only available in the node selected by the engine. Note that if this option is used, the returned Run instance will not access the remote_dir, but the run_dir. If the remote node is unable to access the path (trying to create it if needed), OSIRIS will be started in the run dir and errors will be logged by the queue system.
  • clean_dir (bool) – Whether to remove the files in the directory before execution.
  • prolog (str) – Shell code to run before calling OSIRIS (but once in the remote_dir if asked for).
  • epilog (str) – Shell code to run after calling OSIRIS.
  • create_only (bool) – Whether just to create the files, but not queueing the run.
Returns:

A Run instance describing the execution.
Return type:

Run
duat.run.run_variation(config, variation, run_base, caller=None, on_existing=None, **kwargs)[source]

Make consecutive calls to run_config() with ConfigFiles generated from a variation.

Parameters:
  • config (ConfigFile) – Base configuration file.
  • variation (Variation) – Description of the variations to apply.
  • run_base (str) – Path to the directory where the runs will take place, each in a folder named var_number.
  • caller (int or MPCaller) – If supplied, the calls will be managed by a MPCaller instance. If an int is provided an MPCaller with such a number of threads will be created. Provide an instance if interested in further controlling.
  • on_existing (str) – Action to do if a run of the variation exists. Only the names of the subfolders are used for this purpose, which means the run could be different if the variation or the path have changed. Set to “ignore” to leave untouched existing runs or set to “overwrite” to delete the data and run a new instance. Default is like “ignore” but raising a warning.
  • **kwargs – Keyword arguments to pass to run_config()
Returns:

List with the Run instances in the variation directory.
Return type:

list of Run
duat.run.run_variation_grid(config, variation, run_base, run_name='os-var_', remote_dir=None, on_existing=None, **kwargs)[source]

Make consecutive calls to run_config_grid() with ConfigFiles generated from a variation.

Parameters:
  • config (ConfigFile) – Base configuration file.
  • variation (Variation) – Description of the variations to apply.
  • run_base (str) – Path to the directory where the runs will take place, each in a folder named var_number.
  • run_name (str) – Prefix to the name to use in the grid system.
  • remote_dir (str) – If provided, a remote directory where the runs will be carried, which might be only available in the node selected by the engine. See run_config_grid().
  • on_existing (str) – Action to do if a run of the variation exists. Only the names of the subfolders are used for this purpose, which means the run could be different if the variation or the path have changed. Set to “ignore” to leave untouched existing runs or set to “overwrite” to delete the data and run a new instance. Default is like “ignore” but raising a warning.
  • **kwargs – Keyword arguments to pass to run_config_grid().
Returns:

List with the Run instances in the variation directory.
Return type:

list of Run