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

Install the tool
```
uv tool install processforge
```

Download an example flowsheet

curl -O https://raw.githubusercontent.com/urjanova/processforge/master/flowsheets/hydraulic-chain.json

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.
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.

docs/flowsheets.md : flowsheet JSON format, materials, units, and recycle rules
flowsheets/ : example flowsheets shipped with the repo

License

BSD 3-Clause License

Release files for processforge 0.6.4

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.6.4
File	Size	Uploaded
processforge-0.6.4.tar.gz	250.1 kB	Sep 18, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for processforge 0.6.4
File	Interpreter	ABI	Platform	Reset
processforge-0.6.4-py3-none-any.whl 254.4 kB Sep 18, 2026	Python 3	none	any	Details

Total release size: 504.4 kB

Release files / processforge-0.6.4.tar.gz

Download URL	processforge-0.6.4.tar.gz
Size	250.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`f9b8851141ea8cd69fd9078b479f635eddd9eb9debeb1ddd62d91b26dc2375ab`
BLAKE2b-256 checksum How to use checksums	`20114c4633427aeee870b247f6f8026459fba5e54f415f1d470cc438ecc44eb4`
Upload date	Sep 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.0`

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

Download URL	processforge-0.6.4-py3-none-any.whl
Size	254.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`3cc5c246bee3c6f4fd3115e51e5c30c0746bd43417bc3bae0eac979b753087d9`
BLAKE2b-256 checksum How to use checksums	`225cd56041993a38cfe8b7a657680dbce78dbe74a14f64a19e8f6cdbcbc80886`
Upload date	Sep 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.0`