Limitations
agent-based modeling, abm, bptk, bptk-py, python, business simulation
Limitations
Currently the BPTK_Py framework is geared towards our own need and has a number of limitations. We are more than happy to extend the framework to suit YOUR need, so please let us what you need so that we can prioritize our activities. You can reach us at support@transentis.com
The Rust execution engine
The Rust engine runs System Dynamics scenarios only. A scenario manager registered as agent-based ("type": "abm") always runs in Python and ignores backend, and so does the agent-based half of a hybrid model.
Running on the Rust engine means serialising the model, and these cannot go that way:
- A System Dynamics model with agents and a user-defined function — the function could read what the agents produced. The two halves advance one step at a time, and the engine computes every step of a run at once, so such a function would read a step that has not happened yet. A model that merely has agents is fine; it is the combination that is refused.
- A user-defined function registered with
elementwise=False— it is handed a whole array and answers once, and the engine’s callback answers with one number. - A model compiled from XMILE — the compiler produces a standalone Python class, which has no serialisation at all.
- An installation without the engine — the pure-Python wheel, which is what micropip installs in a browser.
- Parts of the SD DSL the engine does not have yet — the functions irr, lookupinv, lookuparea, rank and interpolate; random functions with a seed; non-negative stocks; and conveyors with their function agecount.
Asking for backend="rust" on a model from that list raises RustBackendError, naming the cause - the function or the stock, where it is one of those. See Execution Backends for how to catch it.
Arrayed models are not in that list. They run on the Rust engine like any other: an arrayed element’s sub-elements are ordinary scalar elements named with brackets, the aggregations became engine-side functions over them, and dot is expanded into a sum of products before the model is handed over. User-defined functions are not in that list either: a model that has them runs on the engine, which calls back into Python at those nodes and says so at [WARN].
A stochastic model that has to be reproducible across a restart — a session externalised to Postgres or Redis and resumed later — must pass an explicit seed to begin_session(). Deterministic models resume exactly regardless.
Running the documentation in a browser
Most pages of this documentation run in your browser, on Pyodide. A page whose model is read from files beside it is shown with its results instead, because those files do not reach the browser. Pyodide is a real Python, but it is not the Python on your machine, and three limits come with it:
- The Python engine only. There is no Rust engine in the browser — the compiled extension has no place to run there.
- One kind of interaction per page load. A slider answers move after move, and a cell edit re-runs everything downstream. Doing both in one session eventually exhausts the browser’s heap and the page goes quiet until you reload it. Every plot leaves its figure behind, and the page shares one heap for everything on it.
- No progress bars.
progress_bar=Trueneeds a lock that the browser platform does not provide, and the run stops rather than slows.
None of this applies when you run the same notebook on your own machine. The Installation page shows how.
Capabilities that need an extra
The base install deliberately does not carry everything. Plotting, the XMILE compiler, the server and Logfire logging each live behind an extra, and using one without installing it raises an error naming the extra. See Installation.
Simulation and XMILE
- Currently the simulator only supports the Euler method, Runge-Kutta Integration is not supported. A Stella model set to Runge-Kutta is transpiled all the same and runs with Euler, so its results differ from Stella’s.
- Which XMILE builtins the transpiler compiles, what it does not compile, and how each builtin is written in the SD DSL: see XMILE in the SD DSL.