rubem.api.Model

class Model(configuration, *, validate_input=True, allow_blocking_problems=False)

Bases: object

A configured model, ready to run.

Build one with from_file() or from_config() rather than by calling the constructor, unless a ModelConfiguration has already been loaded elsewhere.

Parameters:

• configuration (ModelConfiguration) – The loaded configuration.

• validate_input (bool) – Whether an isolated run revalidates the input files and their content when it rebuilds the configuration. It has no effect on configuration, which is already loaded; pass the value the configuration was loaded with.

• allow_blocking_problems (bool) – Whether an isolated run keeps going when the configuration it rebuilds carries blocking problems, as from_file() and from_config() do with the same keyword. It has no effect on configuration either; pass the value the configuration was loaded with.

Methods

from_config	Return the model a configuration document, or a loaded configuration, configures.
from_file	Load a configuration file and return the model it configures.
run	Run the simulation in the current process.
run_isolated	Run the simulation in a fresh spawned subprocess.

Attributes

configuration

The loaded configuration this model runs.

property configuration: ModelConfiguration

The loaded configuration this model runs.

classmethod from_config(config, *, validate_input=True, base_dir=None, allow_blocking_problems=False)

Return the model a configuration document, or a loaded configuration, configures.

Parameters:

• config (dict | ModelConfiguration) – The configuration document (legacy or format 1.0) as a dictionary, or an already loaded ModelConfiguration, which is used as it is. A dictionary is copied, so it can be edited and passed again for another model without changing this one.

• validate_input (bool) – Whether to validate the input files and their content. An already loaded configuration is not validated again; the flag then only says whether an isolated run revalidates when it rebuilds the configuration.

• base_dir (str | PathLike[str] | bytes | None) – Directory the relative paths of the document are anchored on. A dictionary has no anchor unless this is passed. Ignored when config is already loaded.

• allow_blocking_problems (bool) – Whether to load, and run, a document whose inputs carry blocking problems, as in from_file(). For an already loaded configuration the flag only says whether an isolated run keeps going when it rebuilds the configuration.

Raises:

• ImportError – If PCRaster or GDAL are not installed.

• FileNotFoundError – If a raster or table the document names is not there.

• pydantic.ValidationError – If the document does not match the schema.

• ConfigurationError – If the inputs carry blocking problems, unless allow_blocking_problems is set.

Return type:

Model

classmethod from_file(path, *, validate_input=True, base_dir=None, allow_blocking_problems=False)

Load a configuration file and return the model it configures.

Parameters:

• path (str | PathLike[str] | bytes) – The JSON configuration file, legacy or format 1.0.

• validate_input (bool) – Whether to validate the input files and their content.

• base_dir (str | PathLike[str] | bytes | None) – Directory the relative paths of the configuration are anchored on. Defaults to the directory of the file.

• allow_blocking_problems (bool) – Whether to load, and run, a configuration whose inputs carry blocking problems. The checks still run and every problem is kept in configuration.problems; the blocking ones are logged as errors instead of raising ConfigurationError. An isolated run rebuilds the configuration the same way.

Raises:

• ImportError – If PCRaster or GDAL are not installed.

• FileNotFoundError – If path, or a raster or table it names, is not there.

• json.JSONDecodeError – If the file is not JSON.

• pydantic.ValidationError – If the document does not match the schema.

• ConfigurationError – If the inputs carry blocking problems, unless allow_blocking_problems is set.

Return type:

Model

run()

Run the simulation in the current process.

A fresh model framework is built for every call, and sets the clone of its own grid. PCRaster state is process-wide all the same, so successive calls in one interpreter grow the resident memory, and calls must not run at the same time in several threads: they fail or, on the same grid, may write wrong results without any error. See run_isolated().

Return type:

RunResult

Returns:

What the run wrote.

Raises:

• ImportError – If PCRaster or GDAL are not installed.

• Exception – Whatever the simulation itself raises, unchanged.

run_isolated()

Run the simulation in a fresh spawned subprocess.

The configuration crosses as its document (the copy taken when it was loaded) plus its base directory and the validation flags, and is rebuilt on the other side; the result crosses as plain data. The subprocess is started for this call only and the executor is shut down before returning, so the PCRaster state of the run leaves nothing behind. Every call therefore pays a full interpreter start-up.

The spawn start method imports the main module of the caller in the subprocess, so a script that calls this method must guard its entry point with if __name__ == "__main__": to avoid re-running itself, and must be a file: a script read from standard input cannot be imported again. Either mistake kills the subprocess at start-up and is reported as the RuntimeError below.

The call waits for the subprocess. An interrupt that reaches the subprocess as well (Ctrl-C in a terminal) stops the run; one delivered to the calling process alone is raised only after the run has finished.

A configuration problem found while the subprocess rebuilds the configuration reaches the caller as the same ConfigurationError, with its problems, unless the model was built with allow_blocking_problems; any other exception of the run propagates as itself.

The log records of the simulation are emitted in the subprocess, which starts from the default logging configuration: the handlers of the caller do not see them.

Return type:

RunResult

Returns:

What the run wrote.

Raises:

• ImportError – If PCRaster or GDAL are not installed.

• RuntimeError – If the subprocess dies before the run finishes.