Skip to main content

mosox

An LP matrix generator for GMPL (MathProg) and (by extension) AMPL.

Can be used in several ways:

  • Compile an MPS file for solving elsewhere
  • Solve directly with the HiGHS integration, no other binary needed
  • From Python, with data from pandas (or a .dat file), and scenario sweeps

It works for a subset of GMPL (specifically the subset required to run Osemosys). See Known limitations section below.

There are a number of examples of varying complexity in the examples/ directory.

Quickstart

Installation

Using Cargo

cargo install mosox

Using Homebrew (macOS)

brew tap carderne/mosox-tap
brew install mosox

Python

pip install mosox  # or: uv add mosox

Requires Python >= 3.11. Wheels are built for Linux x86_64, macOS arm64 and Windows x64; elsewhere pip builds from source, which needs a Rust toolchain.

Pre-built binaries (macOS, Windows, Linux)

Binaries are built for a small set of systems and architectures. Available to download (compressed) from the Releases page. Please choose the appropriate archive.

Usage overview

Usage overview:

mosox help

LP matrix generator for GMPL

Usage: mosox <COMMAND>

Commands:
  compile    Load and output to MPS
  solve      Solve with HiGHS
  normalize  Normalize an MPS file for diffing
  compare    Compare two normalized MPS files with epsilon tolerance
  help       Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

Compile MPS

Compile MPS for one of the examples in this repo. Output will be written to the provided file:

mosox compile examples/basic/model.mod -o output.mps

Or an example with a separate data file, writing MPS to a file:

mosox compile examples/sets/model.mod examples/sets/data.dat -o output.mps

Solve a model

Results will be saved to the output file:

mosox solve examples/basic/model.mod -o output.txt

# Loading model from model.mod
# Generating matrix
# Matrix compiled in 666.625µs
# Matrix: 3 rows, 2 cols, 6 nonzero
# Solving matrix with HiGHS
# Solved in 1.939083ms
# Objective value: 2200
# Results output to output.txt

Python

Pass data as pandas DataFrames, on top of any data in the model file or a .dat file. Index columns are matched by set name (as in otoole), then VALUE.

import pandas as pd
import mosox

model = mosox.Model.from_file("examples/2d_params/model.mod")
cost = pd.DataFrame({"PLANTS": ["P1", "P2"], "WAREHOUSES": ["W1", "W1"], "VALUE": [9, 11]})

# `update` patches rows; dicts and scalars work too
solution = model.solve(mosox.Data().update({"cost": cost, "supply": {"P1": 120}}))
solution.status, solution.objective
solution["ship"]  # DataFrame: PLANTS, WAREHOUSES, VALUE, MARGINAL

Base data can come from a .dat file (Data.from_dat) or otoole (Data.from_otoole(*otoole.read(...))). Run a sweep over every combination of factors, in parallel:

model = mosox.Model.from_file("examples/osemosys_small/osemosys.mod")
base = mosox.Data.from_dat("examples/osemosys_small/ose_small.dat")
scenarios = mosox.product(
    carbon={"none": {}, "high": {"EmissionsPenalty": 100}},
    discount={r: {"DiscountRate": r} for r in [0.05, 0.10]},
)
run = model.run(scenarios, base, workers=4, keep=["NewCapacity"], store="results/")
for event in run:  # Started, Compiled, Finished, Failed, Skipped
    print(f"{event.done}/{event.total}", type(event).__name__, event.scenario.name)

results = run.results()  # or later: mosox.Results.open("results/")
results.summary          # a row per scenario: status, objective, timings
results["NewCapacity"]   # all scenarios, with scenario, carbon and discount columns

Development

Please install cargo-make:

cargo install cargo-make

The most useful dev commands are listed in Makefile.toml.

You can view available commands by running cargo make.

Formatting, linting

cargo make fmt
cargo make lint
cargo make ci  # fmt-check, lint, test (same as CI)

lint and test enable all features, including the Python bindings, which need Python >= 3.11. If your default python3 is older, point PyO3 at a newer one, e.g. export PYO3_PYTHON=$PWD/.venv/bin/python after uv sync.

Testing

In addition to other tests, this will run mosox against all the examples under examples/ and confirm that the output is identical to the existing MPS files.

cargo make test

This will additionally run a regression test against examples/osemosys_large if present.

cargo make testlarge

Python bindings

Requires uv. uv run builds the extension (unoptimised) as needed.

cargo make py  # ruff format, ruff check, ty check, pytest

Benchmarks

Run performance benchmarks across all examples (except osemosys_large):

cargo make bench

Include osemosys_large (requires the example to be present):

cargo make benchlarge

Run with glpsol comparison (requires glpsol on PATH):

cargo make benchglpsol

Performance vs glpsol (median, release build, Macbook Air M2)

Note that some of the performance advantage over glpsol may be caused by the limitations enumerated below.

Example rows/cols/nonzero N glpsol mosox Speedup
osemosys_small 6k/7k/15k 50 68ms 17ms 4.0x
osemosys_atlantis 180k/230k/510k 10 2.4s 373ms 6.5x
osemosys_large 1M/5M/12M 4 130s 20s 6.5x

Memory usage

The matrix generator uses very roughly 2,000 bytes per non-zero. This is a significant overhead over the 12 bytes per non-zero that would be needed in a format like CSC. However, as the table below shows, the matrix generator will rarely (if ever) use more memory than the solver.

Example Mosox matrix Glpsol matrix HiGHS solver Glpsol solver
osemosys_small 13 MB 12 MB 24 MB 16 MB
osemosys_atlantis 244 MB 287 MB 386 MB 416 MB
osemosys_large 5 GB 5.6 GB 6.5 GB ?

Known limitations

This list of limitations is made with reference to the GNU MathProg Language Reference which can be viewed here or downloaded from the original here.

It is intended that all of these will ultimately be supported, and most of them are "trivial" to add.

Functions

  • The following functions: abs, atan, ceil, cos, exp, floor, gmtime, length, log, prod, round, sin, sqrt, str2time, trunc, Irand224, Uniform, Normal.

Expressions

  • These arithmetic operators: less, div, mod
  • These symbolic operators: & (string concatenation)
  • These set expressions: conditional set expressions
  • String ordering comparisons (<, > etc. between symbolic values)

Sets

  • within and dimen are not enforced on computed sets that fail to evaluate at load (eg sets over tuple domains)

Parameters

  • Type specifiers, relational conditions and superset (in) expressions are only enforced on explicit data and constant defaults, not on computed params (:= expressions) or expression defaults
  • Plain-format data for multi-dimensional params without a slice (eg param p := a x 1 b y 2;) is not supported (it is caught as out-of-domain data)

Variables

  • Bounds specified as expressions (currently only constant accepted)

Constraints

  • Multiple expressions (comma-separated)

Other statements

Support for these statements is not planned (results should instead be parsed from the solver output): display, printf, for.

Metadata

Release files for mosox 0.8.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mosox 0.8.1
File Size Uploaded Provenance Actions
mosox-0.8.1.tar.gz 554.4 kB With provenance Details for mosox-0.8.1.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for mosox 0.8.1
File Interpreter ABI Platform Actions
mosox-0.8.1-cp311-abi3-win_amd64.whl CPython 3.11 abi3 Windows x86-64 Details for mosox-0.8.1-cp311-abi3-win_amd64.whl
mosox-0.8.1-cp311-abi3-manylinux_2_39_x86_64.whl CPython 3.11 abi3 Linux glibc 2.39+ x86-64 Details for mosox-0.8.1-cp311-abi3-manylinux_2_39_x86_64.whl
mosox-0.8.1-cp311-abi3-macosx_11_0_arm64.whl CPython 3.11 abi3 macOS 11.0+ ARM64 Details for mosox-0.8.1-cp311-abi3-macosx_11_0_arm64.whl

Total release size: 39.2 MB

Release files / mosox-0.8.1.tar.gz

Download URL mosox-0.8.1.tar.gz
Size 554.4 kB
Tags Source
SHA-256 checksum
How to use checksums
2926498049fd8d756bdc17002a60c9bef64340a92df13f27c88b0bc598c8e3db
BLAKE2b-256 checksum
How to use checksums
c3ea97bf0876ce0113e841c6ced3feb2cde38d5652274d7f33012bfb0a6b0276
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Release files / mosox-0.8.1-cp311-abi3-win_amd64.whl

Download URL mosox-0.8.1-cp311-abi3-win_amd64.whl
Size 5.4 MB
Tags CPython 3.11 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
c1d86544e613b049156a1a516b004677a9e7707fce47e9759262211a4a610553
BLAKE2b-256 checksum
How to use checksums
1f74012571095b93d95a8079a6e4b54189397ab98aa285281afbbc00b7342320
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Release files / mosox-0.8.1-cp311-abi3-manylinux_2_39_x86_64.whl

Download URL mosox-0.8.1-cp311-abi3-manylinux_2_39_x86_64.whl
Size 28.2 MB
Tags CPython 3.11 Linux glibc 2.39+ x86-64 abi3
SHA-256 checksum
How to use checksums
c89a0d6e895bdae4c1fdcb287b3fb7d51ec35b26251579c8ae1193e2aa1e3b54
BLAKE2b-256 checksum
How to use checksums
9d97aa1fe077041ed74a0eb9d82ea499364169a82593838f6353e2149a5e7abd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Release files / mosox-0.8.1-cp311-abi3-macosx_11_0_arm64.whl

Download URL mosox-0.8.1-cp311-abi3-macosx_11_0_arm64.whl
Size 5.0 MB
Tags CPython 3.11 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
545505f299b30665d001cb5f8c830c77dcc8e870af74a499e14bf27c4c3c9136
BLAKE2b-256 checksum
How to use checksums
fddd6a1d8a031833de7aa7324f0e07dc99cb4e5addae5a83a88d5ed6b3a60271
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Security for mosox 0.8.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 4 files in this release have been uploaded with provenance metadata.

Select from 4 files

Attestation for mosox-0.8.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page