Building the Executable

Building the Executable

ProGRESS can be packaged as a standalone desktop application using PyInstaller. The pre-built executable bundles GLPK for dispatch optimization and HiGHS for PCM. To include additional solvers such as CBC, CPLEX, or Gurobi, you must rebuild the executable on your own machine.

Why Rebuild?

The default progress.spec file locates and bundles the GLPK solver binary (glpsol) and its required libraries. Other solvers are not included in the default build. When you install a new solver on your system, PyInstaller must re-run to detect it and embed it in the executable.

Prerequisites

Requirement	macOS	Windows
Python environment	Python 3.11+ with ProGRESS dependencies	Python 3.11+ with ProGRESS dependencies
PyInstaller	pip install pyinstaller	pip install pyinstaller
GLPK	brew install glpk	Install winglpk and add to PATH
CBC (optional)	brew install cbc	Install COIN-OR and add to PATH
CPLEX (optional)	Install IBM ILOG CPLEX and activate the Python API	Install IBM ILOG CPLEX and activate the Python API
Gurobi (optional)	Install Gurobi and pip install gurobipy	Install Gurobi and pip install gurobipy

Verify Solver Installation

Before rebuilding, confirm that each solver is available on your system PATH:

# GLPK (required)
which glpsol
glpsol --version

# CBC (optional)
which cbc
cbc -version

# CPLEX (optional) — verify the Python API is importable
python -c "import cplex; print(cplex.__version__)"

# Gurobi (optional) — verify the Python API is importable
python -c "import gurobipy; print(gurobipy.gurobi.version())"

If which cbc does not return a path, add the CBC binary directory to your PATH before rebuilding.

Rebuild the Executable

From the repository root, run:

pyinstaller progress.spec --clean -y

The --clean flag forces PyInstaller to discard cached files and re-analyze all imports and binaries. The -y flag overwrites any previous build output without prompting.

The build output is placed in the dist/snl-progress directory:

• macOS: dist/snl-progress/snl-progress.app
• Windows: dist/snl-progress/snl-progress.exe

How the Build Works

progress.spec

The spec file controls what PyInstaller bundles:

1. GLPK detection: The spec file calls shutil.which("glpsol") to locate the GLPK binary. On macOS it also resolves Homebrew-linked shared libraries using otool -L. On Windows it collects .dll files from the GLPK directory.
2. Binary collection: Collected binaries (GLPK, casadi, pybamm) are embedded in the executable alongside all Python packages.
3. Runtime hook: At launch, the executable runs hooks/runtime_hook_casadi.py, which adds the bundled glpk/ and casadi/ directories to the system PATH so the embedded binaries are discoverable.

Adding Other Solvers to the Build

To bundle CBC, CPLEX, or Gurobi in the executable, modify progress.spec to detect and collect those solver binaries. For example, to add CBC:

# After the glpk_binaries block, add:
cbc_binaries = []
cbc_path = shutil.which("cbc")
if cbc_path:
    cbc_binaries.append((cbc_path, "cbc"))

Then add cbc_binaries to the binaries= list in the Analysis call.

For CPLEX and Gurobi, the solvers are typically invoked through their Python APIs (cplex and gurobipy) rather than standalone binaries. These packages are usually included automatically by PyInstaller's import analysis. If they are not detected, add them to the hiddenimports list.

Updating the Runtime Hook

If you bundle additional solver binaries, update hooks/runtime_hook_casadi.py to add their directories to the PATH at runtime. For example:

cbc_dir = os.path.join(bundle_dir, "cbc")
if os.path.isdir(cbc_dir):
    path = os.environ.get("PATH", "")
    if cbc_dir not in path:
        os.environ["PATH"] = cbc_dir + os.pathsep + path

Smoke Test

After building, verify the executable launches and can find the bundled solver:

1. Launch the executable (snl-progress.app on macOS, snl-progress.exe on Windows).
2. Open the Simulation page.
3. Confirm the dispatch solver dropdown shows the expected options.
4. Run a short simulation (1 sample, 24 hours) to verify the solver is invoked.

For command-line verification, you can also inspect the bundled files:

# macOS
ls dist/snl-progress/snl-progress.app/Contents/Resources/glpk/

# Windows
dir dist\snl-progress\_internal\glpk\

---

Next: Additional Features — Degradation models, PCM integration, and multi-period optimization.

Back to Home | Previous: Workflow | Back to README