Installation#

mathspec needs Python 3.12 or above. Install it from PyPI:

pip install mathspec

uv add mathspec

pixi add --pypi mathspec

The version on main installs from git:

pip install git+https://github.com/energy-models/mathspec

To develop against a clone instead, follow contributing.

Editor completion and offline checking#

The YAML keys ship as a JSON Schema, schema/mathspec.schema.json. An editor reads it for key completion, and a job with no Python reads it for a structure check.

Map the schema in VS Code#

Install the Red Hat YAML extension, then map the schema per workspace:

// .vscode/settings.json
"yaml.schemas": { "https://raw.githubusercontent.com/energy-models/mathspec/main/schema/mathspec.schema.json": ["*.spec.yaml"] }

or per file, with a modeline on its first line:

# yaml-language-server: $schema=https://raw.githubusercontent.com/energy-models/mathspec/main/schema/mathspec.schema.json

Check a file without Python#

For a pre-commit hook or a non-Python CI job:

uvx check-jsonschema --schemafile https://raw.githubusercontent.com/energy-models/mathspec/main/schema/mathspec.schema.json spec.yaml

The schema validates structure only. The math inside expression: and where: is checked by to_spec.