DOCSEARCHbyAlgolia
Submit Docs

PySD Documentation

repository·master·Indexed 19 days ago

https://github.com/sdxorg/pysd

PySD is a Python library for executing System Dynamics models, designed to integrate System Dynamics workflows with Big Data and Machine Learning tools. It allows users to translate model files (such as Vensim .mdl) into Python modules, replace model components with custom Python functions, and run simulations via a Python API or command line. Key features include support for submodel extraction, state exporting/loading, netCDF initialization for external data, and integration with R via the PySD2R package.

Tokens
16K
Snippets
53
Records
96
Agent score
64%

What's inside PySD

  1. Overview of PySD

    master
    PySD is a Python library designed for running System Dynamics (SD) models. Its primary goal is to bridge the gap between System Dynamics and the broader data science ecosystem by enabling better integration of Big Data and Machine Learning into the SD workflow. This allows modelers to leverage modern computational tools directly within their simulation environments.

  2. What is PySD and how does it work?

    master

    PySD is a Python library designed to transpile System Dynamics (SD) models built in Stella (using *.xmile format) or Vensim (using *.mdl format) into Python.

    This allows you to:

    1. Load and execute existing SD models within the Python ecosystem.
    2. Parametrize models at runtime.
    3. Leverage Python's data science capabilities (e.g., visualization, machine learning, sensitivity analysis) on your simulation results.

    Core Architecture

    Since version v3.0.0, PySD uses an intermediate Abstract Model Representation (AMR). The process follows these steps:

    1. Parsing: Uses Parsing Expression Grammars (PEGs) to convert *.xmile or *.mdl files into an AMR (pure Python objects).
    2. Building: A builder takes the AMR and writes the corresponding Python code.
    3. Solving: A forward Euler solver executes the generated model.

    This decoupled architecture means the parsing logic is isolated from the building logic, allowing for potential future builders that could output models in other programming languages.

  3. Use Abstract Syntax Trees (AST) for component expressions

    master
    The lowest level of the PySD abstraction is the AbstractSyntax Tree (AST). The AST is used to represent all operations and function calls within a specific component expression. If you are extending the translation or building logic to handle complex mathematical or logical expressions, you will interact with the structures defined in pysd.translators.structures.abstract_expressions.

  4. Supported model formats for translation

    master

    PySD can translate the following model formats into an Abstract Model Representation (AMR):

    • Vensim: Files in the .mdl format.
    • XMILE: Files in .xml, .xmile, or .stmx formats (exported from Vensim, Stella, or other software).

    The translation process uses the Parsimonious library to parse the original models into an abstract syntax tree, which is then crawled to construct the AMR.

  5. Understanding the Python Model and the Model class

    master

    When using the Python builder, PySD constructs a Python class that represents the system dynamics model. This class is stateful, maintaining a dictionary of the current values for all system stocks and the current simulation time.

    Key characteristics of the Model class:

    • Component Functions: The class contains a function for every model component. These functions represent the essential model equations and include metadata such as units, subscript type information, and documentation translated from the original file.
    • Markov Property: The Model class maintains only a single state in memory. All functions must obey the Markov property, meaning the future state of the system must be calculable entirely from its current state.
    • Simulation Output: The .run() method executes the simulation and returns a Pandas DataFrame representing the output. You can use various options to specify which components to return and at which timestamps to take measurements.

  7. Understand PySD limitations and unsupported functions

    master

    PySD does not implement every single feature found in Vensim or XMILE. While most commonly used functions are supported, some models may only run partially.

    Handling Unsupported Functions: When PySD encounters a function or feature that is not yet implemented, it translates it as pysd.py_backend.functions.not_implemented_function. This prevents the translation from failing immediately but may affect the accuracy of the simulation if that specific function is critical to the model logic.

  9. Understand the Abstract Model representation

    master

    PySD uses an AbstractModel representation to decouple the translation process from the building process.

    • Translation: The phase where source code (e.g., Vensim) is loaded into memory and converted into an AbstractModel.
    • Building: The phase where the AbstractModel is used to generate source code in a different target language (e.g., Python).

    This separation allows developers to add support for new source languages or new target output languages independently without affecting the other side of the pipeline. The AbstractModel is designed to retain as much information from the original model as possible to support future output requirements (such as protecting unchangeable constants).

  10. Understand the Model and Macro classes

    master

    The core of PySD's interaction with models is built around two main classes:

    • pysd.py_backend.model.Model: This class implements the functionalities required to load a translated model and interact with it. It inherits from Macro.
    • pysd.py_backend.model.Macro: This class implements functionalities to load and interact with a translated macro. Many of its core methods are also used by the Model class.

    Because Model inherits from Macro, a Model instance possesses all the public methods and properties defined in the Macro class.

  11. PySD Design Philosophy

    master

    PySD follows a specific design philosophy to maintain robustness and focus on System Dynamics (SD):

    • Do as little as possible: Avoid implementing non-endemic SD features like plotting, integration, or fitting; use external tools instead. Stick strictly to SD and avoid overlapping with other disciplines like ABM or Discrete Event Simulation.
    • Use the core language of SD: Limit implementations to the basic XMILE standard and resist the urge to replicate every feature found in commercial vendor tools.
    • Emphasize ease of use: Design for SD practitioners who may not be Python experts by using general Python best practices and strong testing/profiling components.

  12. How the PySD translation and building process works

    master

    PySD follows a three-stage pipeline to convert system dynamics models into executable code:

    1. Translation: PySD translates original models (such as Vensim .mdl files or XMILE files) into an Abstract Model Representation (AMR). The AMR is a language-independent representation consisting of Python data classes that capture all model equations and behavior.
    2. Abstract Model (AMR): This intermediate representation acts as a bridge, ensuring the model logic is decoupled from the source language and the target execution language.
    3. Building: A builder takes the AMR and converts it into source code for a specific programming language.

    Currently, PySD supports translation from Vensim and XMILE, and the only available builder converts the AMR into Python code.