rubem.api

The public Python API of RUBEM.

Three names are public: Model, the entry point that loads a configuration and runs the model; RunResult, the description of what a finished run wrote; and ConfigurationError, re-exported here, raised when a configuration carries blocking problems.

Stability

rubem.api is the supported programmatic surface. Every other module of the package is internal and may change without notice. While the version is below 1.0, a breaking change to rubem.api bumps the minor version and is listed in the changelog.

Process limitation

PCRaster keeps the clone and the raster memory process-wide (setclone is global to the process and the memory of a run is not reclaimed), so repeated Model.run() calls in one interpreter grow the resident memory and must not overlap: every run sets the clone for itself, which lets runs on different grids follow one another, but runs under way at the same time, in several threads, share that state and fail or, on the same grid, may write wrong results without any error. Model.run_isolated() runs the simulation in a fresh spawned subprocess instead, at the cost of an interpreter start-up per call, and keeps that state out of the caller. Parallel runs need one process each: the form to use is a process pool of the caller (concurrent.futures.ProcessPoolExecutor) whose workers call Model.run(), not a thread pool.

Importing this module does not require PCRaster or GDAL; running the model does, and raises ImportError with the installation guidance when they are missing.

Logging

The package reports its progress through the rubem logger and writes nothing to standard output of its own; configure that logger to follow a run. The records of the simulation of an isolated run are emitted in its subprocess, which starts from the default logging configuration and does not inherit the handlers of the caller; the loading of the configuration happens in the calling process and is logged there.

Classes

Model	A configured model, ready to run.
RunResult	What a finished run wrote, enumerated from the configuration.