mpilot.program

class mpilot.program.Program(libraries: Sequence[str] = EEMS_CSV_LIBRARIES, working_dir: str = None)

The Program class contains the command instances that comprise the model, and is responsible for running the model by building a dependency tree and running any “leaf” nodes (those which no other nodes depend on). Before the leaf nodes are run, they resolve their dependencies, which in turn resolve their dependencies, and so on in a recursive nature until the root nodes are run.

Parameters:

  • libraries (Sequence[str]) – A list of command libraries to use in this program. The specified libraries will be used to look up commands. Command names must be unique across libraries; importing two libraries that have the same command names will raise an exception.

  • working_dir (str) – The working directory is used to resolve relative paths used in the model. If None, relative paths are invalid and will raise an exception. Defaults to None.

commands: Dict[str, Command]

A lookup of commands in the program by result name, in the form of {result_name: command, ...}.

command_library: Dict[str, Type[Command]]

A lookup of command classes by name.

working_dir: str

The program’s working directory, if set.

classmethod load_commands(module: str | ModuleType) → None

Discovers and loads commands from the given module and any sub modules. This method is mostly used internally.

classmethod from_source(libraries: Sequence[str] = EEMS_CSV_LIBRARIES, working_dir: str = None)

Creates a program from MPilot source code

find_command_class(name: str) → Type[Command]

Looks up and returns a command class by name, or returns None if the command doesn’t exist.

add_command(command_cls: Type[Command], result_name: str, arguments: Dict[str, Any], lineno: int = None) → None

Adds a command to the program and the arguments required to run it. This is the primary method used when constructing a model programmatically. The command class can be obtained by importing it from the appropriate module, or by using find_command_class() to search for a command by name.

p = Program()
read_cls = p.find_command_class('EEMSRead')
p.add_command(read_cls, 'Var_A', {'InFileName': 'input.csv', 'InFieldName': 'Var_A'})
Parameters:

  • command_cls (Type[Command]) – The class of the command to add. This can be obtained by calling find_command_class() with the name of the command.

  • result_name (str) – The name of the result. This is equivalent to the left side of the = in an MPilot command file: <result> = <command>(<arguments>)

  • arguments (Dict[str, Any]) – A dictionary of arguments to be sent to the command. E.g., {'InFileName': 'input.csv'}

  • lineno (int) – Optional. The line number the command appears on. This should be the first line in which the command occurs in the command file. This is used in error reporting by the command-line program, and may be set to None when being used from Python.

to_string() → str

Returns a string with commands formatted in the MPilot command file syntax.

to_file(file_or_path: TextIO | str) → None

Writes the program as an MPilot command file.

run()
mpilot.program.EEMS_CSV_LIBRARIES = Libraries required for CSV-based EEMS models
mpilot.program.EEMS_NETCDF_LIBRARIES = Libraries required for NetCDF-based EEMS models