Add standalone Julia builder (ODE + MTK backends)

.github/workflows/docker-julia-base.yml

@@ -0,0 +1,44 @@
+name: Build Julia base image
+
+on:
+  push:
+    branches: [feature/julia-mtk-builder, master]
+    paths:
+      - 'docker/julia-base/Dockerfile'
+      - '.github/workflows/docker-julia-base.yml'
+  workflow_dispatch:
+  schedule:
+    # Rebuild weekly so packages stay up-to-date
+    - cron: '0 6 * * 1'
+
+jobs:
+  build-and-push:
+    name: Build Julia ${{ matrix.julia-version }} base image
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        julia-version: ['1.10', '1.11']
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: docker/julia-base
+          file: docker/julia-base/Dockerfile
+          build-args: JULIA_VERSION=${{ matrix.julia-version }}
+          push: true
+          tags: ghcr.io/rogersamso/pysd-julia-base:${{ matrix.julia-version }}

.github/workflows/julia-ci.yml

@@ -0,0 +1,137 @@
+# CI for Julia builder tests.
+#
+# Split into two jobs:
+#   1. julia-python-tests — runs the unit tests and the translation-only
+#      integration tests. No Julia binary needed; these are pure-Python tests
+#      that generate .jl files.
+#   2. julia-numerical-tests — runs only the 27 @pytest.mark.julia tests
+#      that actually execute Julia.
+#
+# The numerical job uses julia-actions/setup-julia + julia-actions/cache,
+# which is the standard pattern across the Julia ecosystem. Cold runs take
+# ~15-20 min; warm cache (subsequent runs on the same Julia version) take
+# ~3-5 min. This avoids the GitHub Actions HOME=/github/home override that
+# breaks Docker-container-based approaches.
+
+name: Julia CI
+
+on:
+  push:
+    paths:
+      - 'pysd/builders/julia/**'
+      - 'tests/pytest_builders/pytest_julia*.py'
+      - '.github/workflows/julia-ci.yml'
+  pull_request:
+    paths:
+      - 'pysd/builders/julia/**'
+      - 'tests/pytest_builders/pytest_julia*.py'
+      - '.github/workflows/julia-ci.yml'
+  workflow_dispatch:
+  schedule:
+    # Run weekly to catch upstream Julia/package breakage
+    - cron: '0 8 * * 1'
+
+jobs:
+  # -------------------------------------------------------------------------
+  # Job 1: unit tests + translation integration tests (no Julia binary needed)
+  # -------------------------------------------------------------------------
+  julia-python-tests:
+    name: Julia builder — Python-only tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install Python dependencies
+        run: |
+          pip install -U pip wheel
+          pip install --prefer-binary -r tests/requirements.txt
+          pip install --prefer-binary -e .
+
+      - name: Run unit tests
+        run: |
+          pytest tests/pytest_builders/pytest_julia.py -v --tb=short
+
+      - name: Run translation integration tests (no Julia runtime needed)
+        run: |
+          pytest tests/pytest_builders/pytest_julia_integration.py -m "not julia" -v --tb=short
+
+  # -------------------------------------------------------------------------
+  # Job 2: numerical tests (require Julia runtime)
+  #
+  # Standard julia-actions pattern: setup-julia installs Julia, cache restores
+  # the depot (~/.julia) between runs. PySD.jl is added to JULIA_LOAD_PATH
+  # so it is visible without Pkg.develop (which would modify the global env).
+  # -------------------------------------------------------------------------
+  julia-numerical-tests:
+    name: Julia builder — numerical tests (Julia ${{ matrix.julia-version }})
+    runs-on: ubuntu-latest
+
+    permissions:
+      actions: write  # allows julia-actions/cache to evict stale caches
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        julia-version: ['1.10', '1.11']
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Set up Julia
+        uses: julia-actions/setup-julia@v3
+        with:
+          version: ${{ matrix.julia-version }}
+
+      - name: Cache Julia depot
+        uses: julia-actions/cache@v3
+
+      - name: Install Julia packages
+        run: |
+          julia --startup-file=no -e '
+            using Pkg
+            # Use a shared named env so all packages (PySD.jl + ODE deps) live
+            # together and JULIA_PROJECT can select it by name in later steps.
+            # Pkg.develop reads PySD.jl/Project.toml (not Manifest.toml), so
+            # it resolves fresh versions compatible with the running Julia version.
+            Pkg.activate("pysd_ci", shared=true)
+            Pkg.develop(PackageSpec(path="pysd/builders/julia/PySD.jl"))
+            # DataInterpolations and NCDatasets are deps of PySD.jl but must
+            # also be direct deps of this env so generated model files can
+            # `using DataInterpolations` / `using NCDatasets` directly.
+            Pkg.add([
+              "OrdinaryDiffEq",
+              "OrdinaryDiffEqLowOrderRK",
+              "DataInterpolations",
+              "NCDatasets",
+              "JSON3",
+            ])
+            Pkg.precompile()
+          '
+
+      - name: Install Python dependencies
+        run: |
+          pip install -U pip wheel
+          pip install --prefer-binary -r tests/requirements.txt
+          pip install --prefer-binary -e .
+
+      - name: Run numerical integration tests
+        env:
+          JULIA_PROJECT: "@pysd_ci"
+        run: |
+          pytest tests/pytest_builders/pytest_julia_integration.py -m julia -v --tb=short

.gitmodules

@@ -1,3 +1,6 @@
 [submodule "tests/test-models"]
 	path = tests/test-models
 	url = https://github.com/SDXorg/test-models
+[submodule "pysd/builders/julia/PySD.jl"]
+	path = pysd/builders/julia/PySD.jl
+	url = git@github.com:rogersamso/PySD.jl.git

Dockerfile.julia

@@ -0,0 +1,40 @@
+# Julia + Python environment for running pytest with @pytest.mark.julia tests.
+#
+# Build:
+#   docker build -f Dockerfile.julia -t pysd-julia-tests .
+#
+# Run:
+#   docker run --rm pysd-julia-tests
+
+FROM julia:1.10
+
+# ── System dependencies ────────────────────────────────────────────────────
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        python3 python3-pip python3-venv \
+        git curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# ── Julia packages ─────────────────────────────────────────────────────────
+# Pre-install ModelingToolkit and dependencies so they are available at test
+# collection time (pytest_julia_integration.py detects Julia/MTK at import).
+RUN julia --startup-file=no -e ' \
+    using Pkg; \
+    Pkg.add(["ModelingToolkit", "OrdinaryDiffEq", "OrdinaryDiffEqLowOrderRK", "DataInterpolations", "JSON3"]); \
+    Pkg.precompile(); \
+    '
+
+# ── Python environment ─────────────────────────────────────────────────────
+WORKDIR /pysd
+COPY . .
+
+RUN python3 -m venv /opt/venv
+ENV PATH="/opt/venv/bin:$PATH"
+
+RUN pip install --no-cache-dir -U pip wheel && \
+    pip install --no-cache-dir --prefer-binary -r tests/requirements.txt && \
+    pip install --no-cache-dir --prefer-binary -e .
+
+# ── Entry point ────────────────────────────────────────────────────────────
+# Run only tests marked with @pytest.mark.julia (requires Julia runtime).
+# Non-Julia tests run in the normal CI without Docker.
+CMD ["pytest", "tests/pytest_builders/", "-m", "julia", "-v", "--tb=short"]

README.md

@@ -27,13 +27,13 @@ See the [project documentation](http://pysd.readthedocs.org/) for information ab
 
 For standard methods for data analysis with SD models, see the  [PySD Cookbook](https://github.com/SDXorg/PySD-Cookbook), containing (for example):
 
-- [Model Fitting](http://nbviewer.ipython.org/github/SDXorg/PySD-Cookbook/blob/master/source/analyses/fitting/Fitting_with_Optimization.ipynb)
-- [Surrogating model components with machine learning regressions](http://nbviewer.ipython.org/github/SDXorg/PySD-Cookbook/blob/master/source/analyses/surrogating_functions/Surrogating_with_regression.ipynb)
-- [Multi-Scale geographic comparison of model predictions](http://nbviewer.ipython.org/github/SDXorg/PySD-Cookbook/blob/master/source/analyses/geo/Exploring_models_across_geographic_scales.ipynb)
+- [Model Fitting](https://nbviewer.jupyter.org/github/SDXorg/PySD-Cookbook/blob/master/source/analyses/fitting/Fitting_with_Optimization.ipynb)
+- [Surrogating model components with machine learning regressions](https://nbviewer.jupyter.org/github/SDXorg/PySD-Cookbook/blob/master/source/analyses/surrogating_functions/Surrogating_with_regression.ipynb)
+- [Multi-Scale geographic comparison of model predictions](https://nbviewer.jupyter.org/github/SDXorg/PySD-Cookbook/blob/master/source/analyses/geo/Exploring_models_across_geographic_scales.ipynb)
 
 ## Why create a new SD simulation engine?
 
-There are a number of great SD programs out there ([Vensim](http://vensim.com/), [iThink](http://www.iseesystems.com/Softwares/Business/ithinkSoftware.aspx), [AnyLogic](http://www.anylogic.com/system-dynamics), [Insight Maker](http://insightmaker.com/), and [others](https://en.wikipedia.org/wiki/Comparison_of_system_dynamics_software)). In order not to waste our effort, or fall victim to the [Not-Invented-Here](http://en.wikipedia.org/wiki/Not_invented_here) fallacy, we should have a very good reason for starting a new project.
+There are a number of great SD programs out there ([Vensim](http://vensim.com/), [iThink](http://www.iseesystems.com/Softwares/Business/ithinkSoftware.aspx), [AnyLogic](https://www.anylogic.com/system-dynamics/), [Insight Maker](http://insightmaker.com/), and [others](https://en.wikipedia.org/wiki/Comparison_of_system_dynamics_software)). In order not to waste our effort, or fall victim to the [Not-Invented-Here](http://en.wikipedia.org/wiki/Not_invented_here) fallacy, we should have a very good reason for starting a new project.
 
 That reason is this: There is a whole world of computational tools being developed in the larger data science community. **System dynamicists should directly use the tools that other people are building, instead of replicating their functionality in SD specific software.** The best way to do this is to bring specific SD functionality to the domain where those other tools are being developed.
 
@@ -53,6 +53,8 @@ git clone --recursive https://github.com/SDXorg/pysd.git
 
 You can use PySD in [R](https://www.r-project.org/) via the [PySD2R](https://github.com/JimDuggan/pysd2r) package, also available on [CRAN](https://CRAN.R-project.org/package=pysd2r).
 
+PySD can also translate models to standalone [Julia](https://julialang.org/) files that run without Python at runtime, using either a plain ODE backend or a [ModelingToolkit](https://docs.sciml.ai/ModelingToolkit/stable/) symbolic backend. See the [Julia Builder documentation](docs/julia_builder.rst) for details.
+
 ## Contributing
 
 PySD is currently a community-maintained project, any contribution is welcome.

docker-compose.yml

@@ -0,0 +1,26 @@
+# Local development: run Julia builder tests in a container.
+#
+# Usage:
+#   docker-compose run julia-tests          # run @pytest.mark.julia tests
+#   docker-compose run julia-unit-tests     # run all pytest_julia.py tests
+
+version: '3.8'
+
+services:
+  julia-tests:
+    build:
+      context: .
+      dockerfile: Dockerfile.julia
+    volumes:
+      - .:/pysd
+    command: >
+      pytest tests/pytest_builders/ -m julia -v --tb=short
+
+  julia-unit-tests:
+    build:
+      context: .
+      dockerfile: Dockerfile.julia
+    volumes:
+      - .:/pysd
+    command: >
+      pytest tests/pytest_builders/pytest_julia.py -v --tb=short

docker/julia-base/Dockerfile

@@ -0,0 +1,30 @@
+ARG JULIA_VERSION=1.10
+FROM julia:${JULIA_VERSION}
+
+# Install Python and git (needed by pytest + submodule checkout in CI)
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends python3 python3-pip python3-venv git && \
+    rm -rf /var/lib/apt/lists/*
+
+# Create a venv so pip installs work without --break-system-packages (PEP 668)
+RUN python3 -m venv /opt/venv
+ENV PATH="/opt/venv/bin:$PATH"
+
+# Store Julia depot outside $HOME so GitHub Actions' HOME=/github/home override
+# doesn't hide the pre-installed packages.
+ENV JULIA_DEPOT_PATH=/opt/julia-depot
+
+# Pre-install and precompile all heavy Julia packages.
+# PySD.jl is intentionally excluded: it lives in the repo and is developed
+# in-place by the CI job, so only it needs recompiling on each run (fast).
+RUN julia --startup-file=no -e '\
+    using Pkg; \
+    Pkg.add([ \
+        "OrdinaryDiffEq", \
+        "OrdinaryDiffEqLowOrderRK", \
+        "DataInterpolations", \
+        "NCDatasets", \
+        "JSON3", \
+    ]); \
+    Pkg.precompile() \
+    '

docs/about.rst

@@ -12,7 +12,7 @@ Some other contributions until release 3.0.0 were:
 - `Julien Malard-Adam <https://github.com/julienmalard>`_ added unicode support for the Vensim parser.
 - `sdCloud.io <http://sdcloud.io>`_ development team made great contributions to improve XMILE support and integrated PySD into their cloud-based model simulation environment.
 - `Eneko Martin-Martinez <https://github.com/enekomartinmartinez>`_ pushed forward the subscripts capabilities for both Vensim and XMILE and included support for several Vensim functions and improved the performance.
-- `Roger Samsó <https://github.com/rogersamso>`_ included a parser for the Vensim sketch and added the option to split a Vensim model per view based on the sketch information.
+- `Roger Samsó <https://github.com/rogersamso>`_ included a parser for the Vensim sketch and added the option to split a Vensim model per view based on the sketch information, and later developed the standalone Julia builder (ODE and MTK backends) together with Claude Code.
 
 The changes made since release 3.0.0 are tracked in the :doc:`whats_new` section.
 

docs/index.rst

@@ -55,7 +55,7 @@ which makes it possible to add builders in other languages in a simpler way
 Why create a new SD simulation engine?
 --------------------------------------
 
-There are a number of great SD programs out there (`Vensim <http://vensim.com/>`_, `iThink <http://www.iseesystems.com/Softwares/Business/ithinkSoftware.aspx>`_, `AnyLogic <http://www.anylogic.com/system-dynamics>`_, `Insight Maker <http://insightmaker.com/>`_, and `others <http://en.wikipedia.org/wiki/List_of_system_dynamics_software>`_). In order not to waste our effort, or fall victim to the `Not-Invented-Here <http://en.wikipedia.org/wiki/Not_invented_here>`_ fallacy, we should have a very good reason for starting a new project.
+There are a number of great SD programs out there (`Vensim <http://vensim.com/>`_, `iThink <http://www.iseesystems.com/Softwares/Business/ithinkSoftware.aspx>`_, `AnyLogic <https://www.anylogic.com/system-dynamics/>`_, `Insight Maker <http://insightmaker.com/>`_, and `others <http://en.wikipedia.org/wiki/List_of_system_dynamics_software>`_). In order not to waste our effort, or fall victim to the `Not-Invented-Here <http://en.wikipedia.org/wiki/Not_invented_here>`_ fallacy, we should have a very good reason for starting a new project.
 
 That reason is this: There is a whole world of computational tools being developed in the larger data science community. **System dynamicists should directly use the tools that other people are building, instead of replicating their functionality in SD specific software.** The best way to do this is to bring specific SD functionality to the domain where those other tools are being developed.
 
@@ -158,6 +158,7 @@ For additional help or consulting, join our slack channel in `sd-tools-and-metho
    installation
    getting_started
    advanced_usage
+   julia_builder
    command_line_usage
    python_api/python_api_index
    tools

docs/installation.rst

@@ -89,6 +89,40 @@ translating models from other system dynamics formats into the XMILE standard, t
 These modules can be installed using pip with a syntax similar to the above.
 
 
+Julia Builder (optional)
+------------------------
+
+To translate models to standalone Julia files, you need Julia 1.10 or later.
+Install via `juliaup <https://github.com/JuliaLang/juliaup>`_:
+
+.. code-block:: bash
+
+   curl -fsSL https://install.julialang.org | sh
+
+Then install the required Julia packages:
+
+.. code-block:: bash
+
+   julia -e 'using Pkg; Pkg.add([
+       "OrdinaryDiffEq",
+       "OrdinaryDiffEqLowOrderRK",
+       "DataInterpolations",
+       "NCDatasets",
+       "ModelingToolkit",
+       "Symbolics",
+       "JSON3",
+   ])'
+
+Finally, install the ``PySD.jl`` companion library from the PySD submodule:
+
+.. code-block:: bash
+
+   git submodule update --init pysd/builders/julia/PySD.jl
+   julia -e 'using Pkg; Pkg.develop(path="pysd/builders/julia/PySD.jl")'
+
+See :doc:`julia_builder` for full usage documentation.
+
+
 Additional Resources
 --------------------
 The `PySD Cookbook <https://github.com/SDXorg/PySD-Cookbook>`_ contains recipes that can help you get set up with PySD.