process-design
/process-design
Write the block flow diagram, process flow diagram, materials and stream table as YAML (process/materials.yaml, process/flowsheet.yaml), generate the BFD/PFD sheets with cheme process build, check balances, fill stream properties, link to the lists and pin the layout. Use at the concept stage before any P&ID, and whenever a stream value, block or step changes.
- Author
- ChemE-as-Code ↗
- Repository
- core ↗
- Licence
- AGPL-3.0
- Last repository change
- 13.11.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.
AGPL-3.0, copyleft: przeróbki udostępniane innym muszą mieć tę samą licencję.
What it does and when to use it
Write the block flow diagram, process flow diagram, materials and stream table as YAML (process/materials.yaml, process/flowsheet.yaml), generate the BFD/PFD sheets with cheme process build, check balances, fill stream properties, link to the lists and pin the layout. Use at the concept stage before any P&ID, and whenever a stream value, block or step changes.
Original author description
Write the block flow diagram, process flow diagram, materials and stream table as YAML (process/materials.yaml, process/flowsheet.yaml), generate the BFD/PFD sheets with cheme process build, check balances, fill stream properties, link to the lists and pin the layout. Use at the concept stage before any P&ID, and whenever a stream value, block or step changes.
How it works
- Purpose and when to use
- Required inputs and missing inputs
- Workflow and tools
- Validation and failure handling
- Outputs and provenance
- Required human judgment
- References
SKILL.md preview
---
name: process-design
description: Write the block flow diagram, process flow diagram, materials and stream table as YAML (process/materials.yaml, process/flowsheet.yaml), generate the BFD/PFD sheets with cheme process build, check balances, fill stream properties, link to the lists and pin the layout. Use at the concept stage before any P&ID, and whenever a stream value, block or step changes.
---
# Process design
## Purpose and when to use
The source of truth is YAML; the BFD and PFD sheets are generated from it. Never edit
`process/BFD.xml` or `process/PFD.xml`: `cheme validate` reports
`cheme.generated-edited` (error) for a hand edit, `cheme.generated-outdated` (warning)
when the YAML changed since the last build and `cheme.generated-version` (warning) after a
cheme-as-code upgrade. The fix for all three is `cheme process build`.
Use it at the concept stage before any P&ID, and whenever a stream value, block or step changes.
## Required inputs and missing inputs
| file | kind (`cheme schema <kind>`) | holds |
|---|---|---|
| `process/materials.yaml` | `process-materials` | components, templates, the property method |
| `process/flowsheet.yaml` | `process-flowsheet` | units, cases, tolerance, feeds, products, blocks, steps, streams, layout |
| `process/BFD.xml`, `process/PFD.xml` | generated | DEXPI 2.0.1 process models with a drawing |
A value nobody knows yet is given as `assumed`, with the reason in `DESIGN.md`.
A process with a reaction starts with its evidence, before a reactor or a conversion is
chosen. Skill `reaction-evidence-search` gathers what papers and patents report in
`process/reaction-evidence.yaml`. Skill `route-selection` compares the routes, records the
model basis and writes `process/reactions.yaml` from it. The reactor itself then follows
skill `reactions`.
## Workflow and tools
### 1. Declare the sheets
In `plant.yaml` `sheets:` add `{id: BFD, kind: bfd, file: process/BFD.xml, title: Block flow
diagram}` (and the PFD with `kind: pfd` once there are steps). They are generated by
`process build`; there is no `generator:` script. The basic gate `process-basic`
(`generated: [pfd]`) fails until the PFD is declared and built.
### 2. Materials
```yaml
components:
- {id: N2, name: Nitrogen, formula: N2, cas: 7727-37-9, molar_mass: 28.014}
- {id: O2, name: Oxygen, formula: O2, cas: 7782-44-7, molar_mass: 31.998}
templates:
- {id: air, title: Air, components: [N2, O2]}
```
Every stream names a `template`; its composition may only use the template's components
(`cheme.process-template`, `process-component`).
### 3. The BFD: feeds, products, blocks, streams
- `feeds` and `products` are the process boundary (DEXPI Source and Sink). Each has `ports`
(`{id: out, direction: out}` on a feed, `{id: in, direction: in}` on a product), and a
`category` (`raw_material`, `product`, `by_product`, `utility`, `wastewater`, `off_gas`,
`solid_waste`, `emission`): a purge or vent without one is invisible to the TEA and LCA
inventories. A utility terminal (steam, cooling water, refrigerant, power) gives `utility:
{kind, level, supply_temperature, return_temperature, min_approach}` from the design basis
(steam also its `pressure`). Every
heater, cooler, machine, column and non-adiabatic reactor needs an energy stream to one.
`cheme process energy` reports the gaps (`cheme.boundary-*`) and the energy balances.
- `blocks` have a DEXPI `class` (`Compressing`, `Cooling`, `Mixing`,
`SeparatingByThermalProcess`, ...) and `ports`: `{id, direction: in | out, kind: material |
energy | information}` (material is the default).
- `streams` run between ports: `from: NODE.port`, `to: NODE.port`, `template`, and per case a
`state`. Every value carries its provenance:
```yaml
- id: S1
title: Air feed
from: AIR.out
to: MAC.in
template: air
state:
design:
pressure: {value: 101.3, provenance: given, source: design basis}
temperature: {value: 288.15, provenance: given, source: design basis}
flow: {value: 98000, basis: mass, provenance: given, source: D-001}
composition: {basis: mole_fraction, values: {N2: 0.79, O2: 0.21}, provenance: assumed}
```
`provenance` is `given` (needs a `source`: a document, a decision id), `assumed` (a guess:
also say why in `DESIGN.md`) or `calculated` (written by cheme-as-code, never by hand). A value
without its own `unit` is in `units:`; pressure is absolute, a gauge value needs its own unit
(`kPa(g)`), `Nm3/h` needs `units.normal_conditions`. Energy streams (`kind: energy`) carry a
`duty`. Further cases (`cases:`) get their own `state` entries.
- A busy BFD (several product or vent streams between the same two blocks): add
`bfd: {aggregate: true}` (or `aggregate: [[COLD_BOX, STORAGE]]` for chosen pairs). Parallel
streams of the same kind and direction are then drawn as one connection labelled with all
their ids (`represents: S6 S7 S8` in its description). Keep every stream in `streams:` with
its own values: the PFD, stream table and balances use the streams, never the connection.
Then:
1. `cheme process build`, then `cheme render process/BFD.xml --png` and look at it.
2. `cheme validate`. Fix every `cheme.process-*` error (each names the YAML line).
Balances: each block's mass flow in and out must agree within `tolerance` (`|in - out| <= abs
+ rel * max(in, out)`); `cheme.process-balance` names the block and both sums.
`process-balance-not-evaluable` (info) names the missing values of the mass balance (flows,
or a composition needed to convert a mole or volume flow); the concept gate
`process-balances` fails on it, so give every boundary stream a flow (`assumed`, with the
reason, where nothing better is known). `process-component-balance-not-evaluable` (info):
the mass balance closes but compositions are missing; the concept gate accepts it, the basic
gate `process-basic` does not, so add the compositions before basic engineering.
3. `cheme process streams` prints the stream table with a provenance letter per value
(G/A/C) and the balance of every block; `--md`, `--csv`, `--json`, `--case`.
### 4. Refine into the PFD
Add `steps`, each in a `block`, with `ports` like a block's. A stream that crosses the block
boundary **keeps its id**: move its end from `BLOCK.port` to `STEP.port` and give that step
port `delegates: <block port>`. Streams between steps of one block are internal: drawn on the
PFD only, never counted in the block's balance. `cheme.process-refine-pending` (info) lists
block ports still used directly once a block has steps; `process-port-open` a port nothing uses.
Add `{id: PFD, kind: pfd, ...}` to `plant.yaml` and build again; the BFD stays the same and so do
its balances (compare `cheme process streams` before and after). Steps check their own
balance where their streams have flows.
A large block can hold **nested blocks**: give a block `parent: P`. The PFD draws it inside P
(with its own steps); the BFD shows only top-level blocks. Where a stream crosses P's boundary
from inside the nested block, chain the delegation: the step port `delegates` the nested
block's port, and that port `delegates: <port of P>`. A stream from the nested block to one of
P's steps needs no delegation to P. `cheme.process-delegation` names the port in the chain
that delegates nothing; a balance of P counts everything inside it. See
`examples/process-nested/` in the cheme-as-code repository.
### 5. Properties
Type compositions and flows only where they are design inputs; `cheme process propagate
--fill` derives the rest through steps their streams determine (by class): pass-through
(`Compressing`, `Pumping`, `Cooling`, heating, `Filtering`, transporting, flow control, and
`ExchangingThermalEnergy` with one material stream in and one out) keeps composition and flow;
`Mixing` sums the mass flows and mixes the compositions; `SplittingMaterial` keeps the
composition and splits the flow by `split: {outlet port: fraction}` on the step (else the one
missing outlet flow is the mass balance remainder); a reactor naming `reactions:` with a
conversion for each (skill `reactions`) gets its outlet from the conversions. A batch still or
solvent swap (`still:` on the step, below) gets its cuts and residue. A step with
`crystallizer:`, `solid_separation:` or `dryer:` (a batch filter-dryer or vacuum dryer: its
`volatiles` dried to a `residual_moisture`, ADR 0057) gets its outlets from that model, and
`cheme process crystallizers` reports their balances and duties. A filter-dryer's filter, wash,
re-filter and dry steps run in one vessel: in `process/recipe.yaml` give them to one unit
procedure as `units: [...]`, with `filter` and `dry` operations `from:` the filter and the
dryer. A separator with a known split (a sieve dryer, a decanter, a scrubber) gives
`recovery:` (below) and gets its outlets from it. Other separators, and
reactors without conversions, are never solved (`cheme.process-propagate-not-solved` lists
their streams lacking values): give those values yourself. Derived values are `calculated` with source `cheme process propagate: ...`
and a fingerprint; never edit them by hand (give the value as `assumed` instead, which propagate
never overwrites), and rerun `--fill` when `validate` reports them stale. A component balance
that becomes evaluable and fails is a design finding: correct the assumed values, and record it
in `DESIGN.md`. Run propagate before `props --fill`.
**Recycles.** Propagate cannot start a loop on its own: the mixer waits for the recycle and the
recycle for the mixer. Never converge a loop by hand (assumed tear values copied back over
runs). Name one stream per loop in `tears:` and let propagate iterate it (ADR 0060):
```yaml
tears:
- stream: S11 # the recycle, between two steps of the loop
initial: {flow: 140, unit: kg/h, basis: mass_fraction, composition: {H2O: 0.6, NAOH: 0.4}}
convergence: {method: wegstein, max_iterations: 100, tolerance: {abs: 0.001, rel: 1.0e-5}}
```
- Give the loop an exit for every component (a purge `split:`, a reaction, a product). A
component that only circulates has no steady state, and the loop does not converge.
- A tear's flow or composition that is a design input (a charge ratio) stays `assumed`.
Propagate iterates only the other. Remove the old hand-converged values so it can.
- Start from a guess of the right order (`initial:`), usually the hand estimate; its fractions
sum to 1 (`cheme.process-tear` otherwise). An empty recycle can leave a splitter remainder
negative, or a still, reactor or filter with nothing to work on, and then the loop does not
close (`cheme.process-recycle`, warning).
- Tear each loop once. Two tears in one loop converge only as fast as plain substitution.
- `cheme.process-recycle` (info) gives the iterations and the worst residual. Tighten
`convergence.tolerance` below the flowsheet's when the loop's gain is near 1: the tolerance
bounds the residual, so the converged loop is within tolerance / (1 - gain) of its steady
state. Record the tears and the tolerance in `DESIGN.md`.
- Nothing that depends on a loop that does not converge is written. Raise
`max_iterations`, give a better guess, or use `method: substitution` with `damping: 0.5`.
**Feeds for a target: design specifications (ADR 0070).** Never scale feeds by hand or by
script to a product rate, a charge ratio or a purity, and never tune a make-up to a loop by
hand. Declare the target in `specs:` and let propagate solve the feed (or a purge split)
together with the tears:
```yaml
specs:
- id: rate # 1000 t/a of product in the recipe's hours_per_year
vary: {stream: S4, initial: 70, with: {S1: 1.89688, S3: 0.26124}} # followers at their charge ratio
target: {stream: S24, quantity: annual, value: 1000, unit: t}
provenance: given
source: "design basis (D-002)"
- id: charge # the make-up that holds the charge ratio of a recycle loop
vary: {stream: S3, initial: 90, with: {S4: 0.133273}}
target: {stream: S9, component: TBA, quantity: ratio, per: {stream: S2, component: K}, basis: mole, value: 8.60}
provenance: assumed
source: "D-004"
```
- Vary a feed stream's flow (remove its given or assumed `flow`; `initial` is the first guess)
or a splitter outlet left out of its `split:` (`vary: {node, port, initial}`). Put every feed
that follows the varied one at a fixed ratio in `with:`. A feed that follows another stream
(caustic per kmol of vented HCl) needs its own spec (`quantity: ratio`), or it stays at its
hand value and the balance flags it.
- Targets: `flow` (a flow unit), `annual` (t/a; `hours` or the recipe's), `ratio` to `per:`,
`fraction` of a component (`basis: mole` or `mass`).
- One spec per degree of freedom: a target its variable cannot move is a warning
(`cheme.process-design-spec`), as is one beyond `low`/`high`. `cheme.process-spec` (validate)
lists declarations that cannot be solved. Record the specs in `DESIGN.md`.
- A batch plant: the spec sets the year-average rate. The recipe's batch size must give it
(`batch = rate x cycle(batch)`): `cheme.recipe-basis` names the batch size that closes it, or
the train's capacity when the cycle grows about as fast as the batch. Set `batch_size` to it
and run `--fill` again.
- A separator with a known split: `recovery: {outlets: {port: {component: share of its inlet
flow}}, provenance, source}`, one outlet left out for the rest, instead of ASSUMED outlet
values from a script, so that a spec upstream reaches past it (`cheme.process-recovery`
checks it).
**Duties from the models (ADR 0059).** Do not copy a reactor's, still's or crystallizer's duty
from a report into its energy stream by hand. Leave the stream's `duty` out and let `cheme
process propagate --fill` write the year-average duty of an isothermal batch or semi-batch
(the reaction heat and the doses' warming), a `still:` (its boil-up's latent heat), a
`crystallizer:` with `energy:` or a conversion step (its declared heats of reaction at their
`temperature`, the streams' sensible heat, less the power its other energy streams bring in,
such as an electrolyser's DC feed: give those streams their duty). It goes on the stream at the
step's `energy_port: PORT`, else on its one energy stream to a heating or cooling utility
(steam, cooling water, refrigerant...): give `energy_port` when the step has several, such as a
reactor heated up by steam and cooled by brine, or a still with condensers, and when its heat
goes to or comes from another block or step (a furnace heating a cracker's coil). Declare a
liquid step's heat of reaction on the liquid basis. Direction matters: a cooling stream runs from the step to
the utility, a heating stream from the utility to the step; the duty is positive. A duty you
keep `assumed` (a heat the model leaves out, such as a heat of absorption) is compared, and
`cheme.process-duty` names both values when they differ: record the difference in
`DESIGN.md`. Before typing such a stream, use the model's own terms (ADR 0063): a dosed
liquid's or gas's heat of dilution or absorption goes in the dose's `heat_of_solution: {values:
{ID: kJ/kmol}, provenance, source}` (negative: released; with it, write the heats of the
reactions consuming a dissolved gas on the dissolved basis, not as a gas, or the absorption
counts twice); the charge's heat-up in `batch.heat_up: true` or `still.heat_up: true` (to the
bubble point, and a swap's feed to the still's temperature); the vessel's steel in the recipe's
`vessel.metal_heat_capacity` (kJ/K, mass x cp), which also lengthens the jacket's heat and cool
times and adds `vessel metal` to the duty of each model in that vessel that changes the
content's temperature (a batch only with `heat_up`: without it the model holds the batch at its
temperature, and the recipe's heat operation holds the content's and the metal's heat; a still
at constant volatility models no temperature and gets none). `cheme
process recipe` reports the heat per batch of each jacket-timed heat-up in a vessel with metal:
the basis for a heater step without a model; do not also count it in a model with `heat_up`. A charged solid's heat of solution, agitation, a one-stage still's condensers (unless
`still.condenser_port` names one) and the dryer (its own `energy.port`) are not written: give
those streams yourself. A still with a `column:` writes both its reboiler (its one heat stream
in, or `energy_port`) and its condenser (its one heat stream out, or `still.condenser_port`):
never type the reflux's share of the reboiler as a stream of its own. A batch's vent condenser
(`batch.vent.condenser`, ADR 0062, see the `reactions` skill) is a different condenser from a
still's: a partial condenser on the vent gas, its duty written on the stream at its own
`vent.condenser.energy_port` (never the jacket's `energy_port`), and the vent's `vapour` adds a
`vent vapour` term (and `condensate return` when it returns to the vessel) to the batch's own
duty, beside a dose's `solution` and the `charge heat-up`.
**Batch distillation and solvent swaps.** Give the still step (class `Distilling`) a
`still:` instead of typing the distillate and the residue:
```yaml
still:
volatility: {model: raoult, provenance: given, source: NIST WebBook} # or constant + alpha
nonvolatile: [PRODUCT]
boilup: {value: 20, unit: kmol/h, provenance: assumed, source: jacket estimate} # kg/h, kW, 1/h
feed: {stream: S12, mode: constant_level} # a solvent swap; or portions: 4, down_to: 0.5
end: {residue: {key: OLD_SOLVENT, mole_fraction: 0.005}} # or distilled, time, temperature
outlets: {distillate: top, residue: bottom} # or cuts: [{outlet, end}], outlets: {residue}
provenance: assumed
```
- Raoult needs each volatile component's Antoine `vapour_pressure` in `materials.yaml`, with
its source and `temperature_range`. `cheme chemistry props` gives the NIST form, which is the
default. A boil-up in kW needs `heat_of_vaporization`, in kJ/kmol: NIST and
`cheme chemistry props` give kJ/mol, so multiply by 1000 (benzene 30.72 kJ/mol is 30720).
- Without these data, `validate` names them (`cheme.process-still`). Look them up (skill
`property-retrieval`), or declare the component `nonvolatile` when it really stays in the
still. Never invent a relative volatility to make the step pass. An assumed `alpha` states
its basis in its source.
- A suspended solid, a salt or an immiscible non-volatile liquid goes in `separate_phase:`, not
`nonvolatile:`: it then does not dilute the liquid in Raoult's law (ADR 0068). `nonvolatile`
is a dissolved solute. Do not declare a component `nonvolatile` only because a template lists
it at 0: a component the charge does not hold needs no vapour pressure.
- A vacuum ramp or a pump-limited forerun is a sequence of `cuts:`, each with its own
`pressure:` and `boilup:` (`unit: m3/h` is the vapour's volume at the still, a vacuum pump's
capacity). A cut ending at a `temperature` per pressure step replaces a residue key set by
hand.
- `heat_up_time: true` gives the heat-up of the charge and the vessel's metal a time at the
still's own boil-up's heat input (not a pump-limited forerun's), added to the recipe's
`distil` from the still: do not also write a hand `heat` operation for it. A jacket that
heats at another rate is a hand `duration` on a `heat` operation, with `heat_up_time` off (a
`heat` with `temperatures` has no batch content on a still).
- The feed's flow is the amount fed per hour of charge, as a semi-batch's dose.
- `cheme process stills` reports the cuts, the residue, the boil-up time and the duty per
batch. The batch comes from `process/recipe.yaml`, whose `distil` operation takes the time
`from:` the still.
- Without `column:` the model is one stage: it strips and swaps solvents but does not purify
a product. An azeotrope (non-ideal liquid) needs a specified split or `process simulate`;
record that in `DESIGN.md`.
**Batch rectification (a column on the still, ADR 0061).** Purify a product in the still with
its column instead of a specified split of the still's distillate:
```yaml
still:
volatility: {model: raoult, provenance: given, source: NIST WebBook}
boilup: {value: 150, unit: kW, provenance: assumed, source: the reboiler} # the whole reboiler
column:
stages: 10 # theoretical stages, the still included
reflux: constant # with ratio; or constant_distillate:
ratio: 2 # distillate: {key: PRODUCT, mole_fraction: 0.999}
# maximum_ratio: 6
provenance: assumed # or minimum_reflux_factor: 1.3 instead of stages
source: packed column, about 10 theoretical stages
cuts:
- {outlet: product, end: {purity: {key: PRODUCT, fraction: 0.998}, basis: mass}}
- {outlet: offcut, end: {residue: {key: PRODUCT, mole_fraction: 0.05}}}
outlets: {residue: bottom}
provenance: assumed
```
- The `boilup` is the reboiler's, not the net distillate rate: `(R + 1)` moles boil up per
mole distilled, and the time and the duty follow. Give the still an energy stream in from
steam (the reboiler) and one out to cooling water (the condenser); propagate writes both.
Delete a typed reflux share (a stream for "the boil-up returned as reflux"), a column step
with a specified split and its return to the pot.
- `cheme process stills` gives each cut's purity and recovery, the reflux at the start and
the end, the boil-up time and the duties. A note says when a constant distillate reached its
`maximum_ratio` (its purity falls from there) or a cut's end was reached at once.
- The shortcut has no holdup and uses Gilliland's correlation: it gives a leaner distillate
than a rigorous column at the same stages and reflux. State the stages and reflux you
assumed in `DESIGN.md`, and size the column and condenser elsewhere.
`cheme process simulate --fill` solves the whole flowsheet in DWSIM, separators, exchangers,
columns and recycles included, from the feeds and the specs in `process/simulation.yaml`; see
the skill `process-simulation`. It writes what propagate cannot (temperatures, pressures, the
outlets of separators) and reports where an assumed value contradicts the energy balance.
`cheme process props --fill` (cheme-as-code installed with the `props` extra) writes `phase` and
`calculated: {molar_mass, density, enthalpy}` with provenance `calculated`, a source and an
input fingerprint, and records the method (its `package`, models, validated range, benchmark
and package versions) in `materials.yaml` `property_method`. It never overwrites given or
assumed values. Enthalpy is on ideal gas at 298.15 K, which needs
`units.enthalpy_reference: {state: ideal_gas, temperature: 298.15}`.
**Property packages.** A process uses one benchmarked package; nothing outside its validated
range is calculated:
| package | components | claimed | benchmark |
|---|---|---|---|
| `air-pr-chemsep` | N2, O2, Ar | 77 to 315 K; vapour 100 to 3200 kPa(a); liquid and two-phase 100 to 600 kPa(a) (Peng-Robinson, ChemSep kij, COSTALD liquid density) | NIST WebBook reference EOS values, `tests/test_process_props.py` |
| `syngas-pr-vapor` | H2, N2, Ar, CH4, CO, CO2 and their mixtures; NH3 pure, and in mixtures with H2, N2, Ar, CH4 up to mole fraction 0.25 (Ar and CH4 then up to 0.10 and 0.20) | vapour only, 250 to 1000 K, 100 to 30000 kPa(a), in per-component boxes (cold, dense gas excluded; CO to 500 K; CH4 to 625 K, in mixtures up to mole fraction 0.2026 to 673.1 K; NH3 pure 350 to 725 K, dilute 320 to 725 K, away from saturation) | CoolProp 8.0.0 reference EOS, GERG-2008 mixtures and the Neumann et al. (2020) NH3 mixture models; measured N2-NH3/Ar-NH3 (Date 1973) and hot H2-CO2-CH4 (Cheng et al. 2019) densities; density within 2 % (pure) / 3 % (mixtures, measured), enthalpy differences within 300 kJ/kmol, `tests/test_property_packages.py` |
| `water-methanol-pcsaft-liquid` (extra `saft`: feos) | water, methanol and their mixtures, water up to mole fraction 0.75 (0.64 below 323.15 K) | liquid density only, PC-SAFT: methanol 240 to 420 K, pure water 360 to 550 K, mixtures to 420 K, to 60 MPa(a); no enthalpy, exergy, VLE or viscosity; liquid at 1.2 times PC-SAFT's bubble pressure or above, nearer only with the phase given or assumed `liquid` | CoolProp 8.0.0 reference EOS (IAPWS-95, methanol); measured densities (Coquelet et al. 2005, Safarov et al. 2004) within 1 %; measured bubble points for the 20 % phase margin, `tests/test_property_packages_pcsaft.py` |
- Run `cheme process props --coverage` first: it names the package (the one recorded as
`property_method.package`, else the one covering the most streams' component sets) and, per
stream, whether it is covered or why not, with the nearest package and what it lacks
(component, pair, temperature-pressure box, a mole fraction above a box's or a pair's
limit). It writes nothing and needs no thermo.
- To use a package for a process whose streams it does not all cover, set
`property_method: {package: <id>}` in `materials.yaml`; an unknown id is an error
(`cheme.process-property-package`). Streams outside it are refused, never computed with
another method.
- What no package covers (water and methanol as vapour, with other components or outside the
liquid boxes, their enthalpies, ammonia above mole fraction 0.25 or with CO or CO2, liquid
synthesis products, hot converter gas with CH4 above 673.1 K or above mole fraction 0.2026
beyond 625 K, CO above 500 K) stays refused: give such values with
their source (`given`, or `assumed` with the reason), or run the flowsheet in
`process simulate` with a method its skill accepts. Do not widen a range in `materials.yaml`
to make a stream pass (a recorded range only narrows the package's).
- **Adding a package** (a cheme-as-code change, not a plant edit): add a `Package` to
`domains/process/property_packages.py` (adapter, EOS and models, BIP source, components by
CAS, validated phases, per-component boxes, benchmarked pairs and any mole-fraction limits
of a box or a pair) and a test that compares
the adapter's own results with an authoritative reference over every claimed box and pair
(a reference equation of state evaluated by a pinned package, or published data with the
source cited in the test), with the tolerance recorded in `benchmark.tolerances`. A
component, phase, pair or region the test does not cover stays out of the claim; a failing
point narrows the claim, never the tolerance. Never type in reference values without a source.
- Anything else (components no package covers, solids, a pressure that is not absolute and
positive, a given phase the flash contradicts beyond saturation) is refused, nothing is
written, and the warning says why (`process-property-out-of-range`, `-unsupported`, `-phase`,
`-metastable`). A phase refusal is usually a design finding: the stated temperature and
pressure do not give that phase. Record it in `DESIGN.md`; do not change the numbers to make
it pass. `--fill` exits 3 when it refused a stream and names them on the summary line.
- A stream at its dew or bubble point (a column's vapour product, a saturated liquid) can land a
hundredth of a kelvin on the wrong side of the line in Peng-Robinson. Give or assume its phase
(`vapor` or `liquid`, with the reason as source): `--fill` then calculates it on that phase's
root of the equation of state at T and P (liquid density still COSTALD), marks every value's
source `phase-constrained <phase> root (...; flash <phase>, dG/RT ...)`, and reports it
(`process-property-phase-constrained`, info). It is refused when the root is metastable by
more than 0.01 RT in molar Gibbs energy against the stable flash (about 0.1 K across the
saturation line of N2 or O2 near 1.3 bar(a); `process-property-metastable`) or does not exist
(beyond the spinodal; `process-property-phase`). Changing the stated phase makes the values
stale.
- After an input changes, `validate` reports `cheme.process-calculated-stale` until `--fill`
recalculates; a refused recalculation keeps the old values and they stay stale.
- `cheme process build` exports the calculated values and phase into the BFD/PFD stream
material states (density, specific enthalpy per kg, phases; molar mass as a description
line). Stale values are left out of the sheets (the description names them): run `--fill`,
then `build`, before handing a sheet on.
- `--check` recalculates and only reports (exit 1 on a warning).
### 6. Links to the plant
`links:` on blocks, steps, streams, feeds and products tie the flowsheet to the lists:
```yaml
links:
- {target: equipment, ref: K-201}
- {target: line, ref: A-201, sheet: P-02}
- {target: instrument, ref: FIC-1101}
```
`target` is `equipment | line | instrument | sheet`; several links per object are fine. A
`sheet:` scope must be a declared sheet, and the list must not place the item on another one.
Links resolve against the equipment, line and instrument lists and `plant.yaml`'s sheets.
Unresolved links are info in `validate`, a warning in the concept gate (`process-links-concept`)
and an error in the basic gate (`process-links`). When a tag or line number changes, change the
link in the same commit (skill `lists-sync`).
### 7. Layout
The layout is generated (layers left to right, recycles routed back). To keep positions:
`cheme process layout --view bfd --pin` (or `--view pfd`, optionally only some ids) writes
them into `layout.bfd` / `layout.pfd` of `flowsheet.yaml`, keyed by object id; later builds keep
them, and you move a node by editing its numbers. A title rename moves nothing; a changed id is
a new object and loses its pin.
## Validation and failure handling
Run `cheme validate` and fix every `cheme.process-*` error. A failing balance or a refused
phase is a design finding: record it in `DESIGN.md`; do not change the numbers to make it pass.
`cheme maturity` says which calculation level the evidence supports (docs/framework/maturity.md).
A `kind: maturity` gate in `checks/checks.yaml` (`require: [balanced]`, optionally
`max_claim: true` against the `process.yaml` claim) fails below that level and names each failing
requirement with its file, rule and hint. Add the evidence it names (a source, a closed balance);
never relabel an assumed value as given to pass it. `require: [engineering]` runs the whole
validation and is slow on a large plant.
## Outputs and provenance
### 8. DESIGN.md and the next stage
`DESIGN.md` keeps decisions and their reasons (`D-0xx`) and cites them as `source:`; the numbers
live in the YAML only. Replace any hand-written stream table with
`cheme process streams --md` output, marked as generated, or a pointer to it. The P&IDs start
from the PFD (skill `pid-draft`): every step becomes equipment, every stream a line, and each gets
its link back.
Commit the YAML and the regenerated sheets together; `cheme validate` must be clean.
## Required human judgment
Separator and reactor values, assumed values and the decisions (`D-0xx`) in `DESIGN.md` are
design choices: cheme-as-code checks them but does not make them.
## References
- `cheme schema process-materials`, `cheme schema process-flowsheet`
- skills `lists-sync` and `pid-draft`; for reactors `reaction-evidence-search`,
`route-selection` and `reactions`
- `examples/process-nested/` in the cheme-as-code repository
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · ChemE-as-Code/core | 100 | AGPL-3.0 |
| cbrock84/headcount | 90 | MIT |
Database snapshot: 13.11.2026 · package version d11cc23b767c (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100neqsim-pfd-layout-review
Mandatory deterministic layout review of every process flow diagram (PFD, BFD, P&ID sketch, flow/network diagram) before use. USE WHEN: a flow diagram is generated, redrawn or inserted in a report - runs `neqsim pfd-check` (overlaps, label/line/box collisions, crossings,… - 85flowsheet-process-model-vocabulary
Vocabulary of the DEXPI process model behind the BFD and PFD - process steps, hierarchy grain, the step taxonomy, streams, ports and compositions - for naming flowsheet steps precisely. Use when describing what a process does rather than what the P&ID draws. - 90flowsheet-diagram-types
What belongs on a BFD, PFD, P&ID and the utility, flare and tie-in drawings, how they differ, and which conventions are universal and which are project-specific. Use when deciding what a drawing should contain or which drawing a question is about. - 100process-study-report
Produces a complete, validated engineering process-study report (Word + PDF) from a solved NeqSim ProcessModel or ProcessSystem: engineering basis, all-stream/all-case tables, balances, BFD and A3 PFD sheets (SVG/PDF), standards register (ISO 10628, NORSOK P-002) and a… - 100pfd-generator
Generate a conceptual PFD (process flow diagram) as an editable SVG, along with the Python script that produced it. Use when the user describes a process and asks to draw, diagram, sketch, or visualize it; when they mention a P&ID, PFD, control loop drawing, or cascade control;… - 100pfd-generator
Generate a conceptual PFD (process flow diagram) as an editable SVG, along with the Python script that produced it. Use when the user describes a process and asks to draw, diagram, sketch, or visualize it; when they mention a P&ID, PFD, control loop drawing, or cascade control;…