Limitations

List the limitations of the BPTK-Py framework.
Keywords

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

The Rust execution engine

The Rust engine runs System Dynamics scenarios only. Agent-based and hybrid models always run in Python, whatever backend you ask for.

Running a model on the Rust engine means serialising it, and not every model can be expressed that way. Two things it cannot take:

  • User-defined functions. A function you wrote yourself in Python has no counterpart in the engine.
  • Arrayed aggregations. The array API is a Python-level concept; the engine sees flat scalar elements, and the aggregation operators over a dimension have no equivalent there.

When it meets one of these, the scenario does not fail — it continues on the Python engine and the reason goes to the log. You lose the speed, never the result. Two consequences are worth knowing:

  • The fallback is per scenario and lasts for the session. Once a scenario has fallen back it stays on Python until you start a new one.
  • A fallback is only visible in the log. Nothing is raised, so a run that you expected to be fast and was not is worth a look at the log before it is worth profiling.

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 run_scenarios(). Deterministic models resume exactly regardless.

Running the documentation in a browser

Every page of this documentation runs in your browser, on Pyodide. That 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=True needs 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

Here are the known limitations:

  • Currently the simulator only supports the Euler method, Runge-Kutta Integration is not supported.

  • The SD model transpiler for XMILE models only supports regular stocks, flows, biflows and converters. Non-negative stocks and discrete modeling elements (such as ovens and conveyors) are not supported.

  • Subranges for arrays are currently not supported.

  • The inner product operator for arrays is currently not supported.

  • Special notations for arrays (e.g. N1:N2 and @) are currently not supported.

  • The random number operators (LOGNORMAL, LOGISTIC etc.) support seed but uses the Python seed and random number generator as the Stella Architect random number function is not open source. Secondly, these operators only support the mandatory arguments (usually mean/scale/stddev) as given in in the Stella documentation

  • INT is transpiled to Python’s math.floor. The two agree for positive numbers and differ for negative ones, where Stella truncates towards zero and floor rounds down: INT(-2.5) is -2 in Stella and -3 here.

  • The following table gives an overview of all XMILE builtins, whether they are supported by the SD model transpiler for XMILE and their equivalent in the SD DSL library – blank cells indicate that the operator is currently not supported. We are working hard to ensure support for all operators is included ASAP. Built-ins pertaining to discrete elements are not listed.

    Entries written Element.arr_… are methods on an arrayed model element rather than functions in sd_functions; see Element.

Built-In SD model transpiler SD DSL equivalent
ABS x abs
AND x And
ARCCOS x arccos
ARCSIN x arcsin
ARCTAN x arctan
BETA x beta
BINOMIAL x binomial
COMBINATIONS x combinations
COS x cos
CGROWTH x -
CLOCKTIME x -
COSWAVE x coswave
COUNTER x -
DELAY x delay
DELAY1 x -
DELAY3 x -
DELAYN x -
DERIVN x -
DT x dt
ELSE x If
EXP x exp
EXPRND x exprnd
ENDVAL x -
FACTORIAL x factorial
FORCST x -
FV x -
GAMMA x gamma
GAMMALN x gammaln
GEOMETRIC x geometric
HISTORY x -
IF x If
INF x Inf
INTERPOLATE x -
INIT x -
INT x floor
INVNORM x invnorm
IRR x -
LOG10 x log10
LOGISTIC x logistic
LOGNORMAL x lognormal
LOOKUP x lookup
LOOKUPAREA x -
LOOKUPINV x -
LN x ln
MAX x max
MEAN x Element.arr_mean
MIN x min
MOD x % (simply use the Python mod operator)
MONTECARLO x montecarlo
NAN x nan
NEGBINOMIAL x negbinomial
NORMAL x normal
NORMALCDF x normalcdf
NOT x Not
NPV x -
OR x Or
PARETO x pareto
PERCENT x -
PERMUTATIONS x permutations
PI x pi
PMT x -
POISSON x poisson
PREVIOUS x -
PULSE x pulse
PV x -
PROD x Element.arr_prod
RANDOM x random
RANK x Element.arr_rank
RAMP x -
REWORK - -
ROUND x round
ROOTN x -
RUNCOUNT - -
SAFEDIV x -
SELF x -
SENSIRUNCOUNT - -
SIN x sin
SINWAVE x sinwave
SIZE x Element.arr_size
SMTH1 x smooth
SMTH3 x -
SMTHN x -
SQRT x sqrt
STARTTIME x starttime
STDDEV x Element.arr_stddev
STEP x step
STOPTIME x stoptime
SUM x Element.arr_sum
TAN x tan
THEN x If
TIME x time
TREND x trend
TRIANGULAR x triangular
UNIFORM x uniform
WEIBULL x weibull