Skip to main content

Processforge

processforge-logo

A lightweight Python framework for process simulation, coupling hydraulic, thermal, and reactor workflows.

Install

Install the pf command-line tool with uv:

uv tool install processforge

For CoolProp-backed units:

uv tool install "processforge[coolprop]"

Optional solver backends:

uv tool install "processforge[eo]"
uv tool install "processforge[eo-casadi]"
uv tool install "processforge[modelica]"

Quick start

  1. Install the tool

    uv tool install processforge
    
  2. Download an example flowsheet

    curl -O https://raw.githubusercontent.com/urjanova/processforge/master/flowsheets/hydraulic-chain.json
    
  3. Initialize, plan, and apply

    pf init flowsheets/hydraulic-chain.json
    pf plan flowsheets/hydraulic-chain.json
    pf apply flowsheets/hydraulic-chain.json
    

    plan validates the flowsheet (schema, DOF, units) without running the solver; apply solves it and stores a snapshot.

  4. Look at the output

    pf apply (and pf run) write a single unified archive under outputs/:

    • outputs/<base>.pfarchive/ — the unified store for a flowsheet's solved state and outputs:
      • snapshots/ — Zarr store of converged state vectors (one group per successful pf apply), each with x/x_delta arrays and config/var-name/metadata attributes, plus a latest pointer (powers warm-start, drift detection, and homotopy).
      • runs/<run_id>.json — the run manifest: every stream and unit engine output (values, units, dtypes, shapes) and run provenance (backend, version, flowsheet hash).
      • outputs/streams/<name>.json — per-stream timeseries from the solve.
      • artifacts.json — content-addressed registry of all output artifacts (local + remote URIs).
      • index.json — field_name → occurrences index for fast cross-run lookups.
      • latest_run — plain-text pointer to the most recent run.
    • outputs/<base>_divergence.json — written only when both direct and homotopy solves fail on pf apply, capturing drifted params, solver stats, and top residual violators.

    For dynamic flowsheets with Tank units, use pf run (not pf apply, which is steady-state EO only) to solve with the dynamic engine.

Python API

Low-level API

from processforge import EOFlowsheet, validate_flowsheet

config = validate_flowsheet("flowsheets/hydraulic-chain.json")
fs = EOFlowsheet(config, backend="scipy")
results = fs.run()

High-level runner (web-app friendly)

from processforge import run_flowsheet

result = run_flowsheet("flowsheets/hydraulic-chain.json")
print(result.run_id, result.status, result.remote_uris)

run_flowsheet and apply_flowsheet perform the full CLI lifecycle (validate, health-check, solve, persist, and upload the pfarchive to S3) and return structured results instead of calling SystemExit. See docs/usage.md for a FastAPI + S3/Railway example.

Usage

See the usage guide for CLI commands and workflows.

Individual providers (e.g. FESTIM, OpenMC) can be run via Docker images using the provider image contract.

Flowsheets

The core of Processforge is the flowsheet JSON format, which defines materials, units, and recycle rules. See below for more information on the formats and example flowsheets.

License

BSD 3-Clause License

Metadata

Release files for processforge 0.7.3

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

Source distribution (sdist)

Source distribution for processforge 0.7.3
File Size Uploaded Provenance Actions
processforge-0.7.3.tar.gz 284.2 kB Without provenance Details for processforge-0.7.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for processforge 0.7.3
File Interpreter ABI Platform Actions
processforge-0.7.3-py3-none-any.whl Python 3 none any Details for processforge-0.7.3-py3-none-any.whl

Total release size: 563.9 kB

Release files / processforge-0.7.3.tar.gz

Download URL processforge-0.7.3.tar.gz
Size 284.2 kB
Tags Source
SHA-256 checksum
How to use checksums
33737e1fe06ca6bb4c7b03f5aca34b64af0e44d885d8b21f1f345250e5303689
BLAKE2b-256 checksum
How to use checksums
5d148052b7b257d71914f7802faabb4acbfc8f204e9d405a3da9263d9b78798f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.0

Release files / processforge-0.7.3-py3-none-any.whl

Download URL processforge-0.7.3-py3-none-any.whl
Size 279.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
62bbf1aab2601ea21426f7e92ab525ee7bc2c932bb761991abf9c68cda6330cf
BLAKE2b-256 checksum
How to use checksums
9c584c3319bebdb34de645616a2a9cf5d0e7b08cd5a4891db2c5b060f02d7ae3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.0

Security for processforge 0.7.3

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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

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.

Release history Release notifications | RSS feed

This release

0.7.3 This release

2 release files No provenance

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