Ratelab user guide

Getting started: your first model in two minutes

For education and preliminary design. Results must be checked by a qualified professional and are not a substitute for code-compliant design or licensed engineering judgement.

Ratelab models reaction kinetics and ideal reactors: you write a reaction network, choose a reactor, and the tool integrates the stiff ODEs, solves steady states, sizes reactors, fits rate laws to data and reports yield and selectivity. Everything runs in your browser; your documents are never uploaded.

1. Open the Network workspace (Alt+1). The default document has species A and B and one reaction "A -> B". Edit the equation, for example "A -> B" followed by a second reaction "B -> C" (use "add missing" to create C).
2. Set the rate constant A of each reaction (with Ea = 0 the number is simply k, in 1/s for a first-order step).
3. Press Alt+2 for the Reactor workspace, keep Batch, set the end time and press Ctrl+Enter. Concentration profiles, step statistics and a final-state table appear.
4. Try Examples (header): the Robertson stiff network, an exothermic CSTR with three steady states, a gas-phase PFR with volume change and fitting demonstrations.
5. Save the document with Ctrl+S. It is autosaved in this browser as well.

Ctrl+K opens the command palette: type "pfr", "csv" or an example name. Press ? for the list of shortcuts.

Units and conventions

Rates are net rates of the reaction as written: r = kf prod C^alpha - kr prod C^beta in mol/(L s). The formation rate of species i is the sum over reactions of nu_ij r_j. Concentrations are clipped at zero inside the rate laws, so numerical undershoot never creates imaginary powers.

Network workspace: species, equations and rate laws

Species have a name, an initial or feed concentration c0 and, only if you use an energy balance, a molar heat capacity cp. Reactions are typed as equations.

• Arrows accepted: ->, =>, →, <=>, <->, ⇌ and "=" (the last three are reversible).
• Elementary: the orders are the coefficients on the reactant side (and the product side for the reverse term).
• Power law: choose "power law" and enter orders such as "A:0.5, B:1.5". Orders may be zero or fractional; the rate of a zero-concentration species with order below one has no derivative, which the solver treats as zero.
• Arrhenius: k(T) = A exp(-Ea/(R T)). Setting Ea = 0 makes k a plain constant equal to A. The panel shows kf at the reactor temperature.
• Reversible with equilibrium constant: give K at a temperature; kr = kf/K(T). K(T) integrates the van't Hoff equation with dH(T) = dH + dCp (T - Tref), dCp = sum nu_i cp_i (cp needed only if dCp is not zero). K is on the concentration basis (mol/L).
• Reversible with its own Arrhenius constant: give reverse A and Ea. The tool warns when a reversible power-law reaction with an equilibrium constant uses orders that differ from the stoichiometry, because it is then not thermodynamically consistent.

The right-hand side lists the compiled rate expressions, the rate constants at the current temperature, the stoichiometric matrix and the conserved combinations (left null space of the stoichiometric matrix), for example total concentration in A -> B -> C.

Stiff integration, error control and the Jacobian

Two implicit methods are available. Radau IIA is a three-stage, fifth-order, L-stable Runge-Kutta method solved with a simplified Newton iteration (default). Rosenbrock 2(3) is the L-stable linearly implicit pair of Shampine and Reichelt (1997) (cheap, lower order, useful as an independent cross-check).

• Error control: mixed tolerance, scale = atol + rtol max(|y|, |y_new|), RMS norm, step-size controller with safety factor 0.9. The default rtol is 1e-8 and atol 1e-12 mol/L.
• Output times are hit exactly (the step is shortened to land on each), so no interpolation error enters the tables.
• Jacobian strategy: the reactor systems differentiate the rate laws analytically (product rule in the concentrations, chain rule through temperature, volume and, for gas flow, through C = kappa F / (T F_T)). The Jacobian is evaluated once at the start of every step and frozen during the Newton iteration. A forward-difference Jacobian (delta = sqrt(eps) max(|y|, atol/rtol)) is used for user-defined systems that supply none.
• The Verify view checks every analytic Jacobian against finite differences and shows that the analytic and finite-difference runs agree.
• Step failures are reported (step-size underflow, step limit, Newton failure); partial results are kept.

Reactor workspace

• Energy: isothermal, adiabatic or heat exchange (UA in J/(s K), or J/(s K L) per reactor volume for a PFR, coolant Ta). The balance is sum(C cp) dT/dt = -sum dH_j(T) r_j + inflow enthalpy + heat exchange, with dH_j(T) = dH + dCp (T - Tref).
• Always include the solvent as an inert species with a cp and its concentration when you use an energy balance; a model whose contents have zero heat capacity is rejected.
• Gas phase: PFR and steady CSTR only, with volume change from the mole count and temperature. c0 values are concentrations at the feed temperature and pressure. A transient gas CSTR is not offered: for a gas CSTR the Reactor workspace shows the steady state only, and a saved document asking for a gas batch or semibatch transient shows the refusal with a one-click switch to the liquid phase.
• Liquid CSTR steady states: multi-start Newton with de-duplication. Stability uses a scaled matrix QR eigensolver with eigenpair residual checks; numerically marginal or unresolved spectra are indeterminate. Gas CSTR steady solving uses one Newton start, without a multiplicity search or stability calculation. The Stability column, the CSV export and the report use four words: stable, unstable, indeterminate (finite spectrum on the numerical boundary; no conclusion) and unavailable (no spectrum computed, always the case for a gas CSTR).
• Heat generation and removal curves (single key reaction) show where G(T) = R(T); the mass balance is solved for each T, which is unique when the rate falls with extent (true for nth-order and reversible kinetics).
• Recycle: liquid CSTR or PFR only. A fraction phi of the effluent returns at its outlet temperature, without a cooler. Coupled material and sensible-enthalpy balances determine the mixed inlet and outlet; the reactor runs at Q/(1 - phi). With an energy balance the mixed inlet and effluent temperatures are shown under the recycle table. Gas recycle is refused: the checkbox is disabled for gas reactors, and a saved gas document with recycle shows the refusal and a button to turn recycle off.

Inference workspace: sensitivity, joint fitting, bootstrap and mechanisms

Alt+8 opens the Inference workspace. It works on isothermal batch concentration kinetics (mol/L, s, K) and runs every analysis in the background engine with a progress bar and a Cancel button; Cancel stops the engine at once and starts a fresh one. If the browser cannot start the background engine, these analyses are disabled rather than run on the page.

• Shared parameters: reaction, field (A, Ea, order, K, reverse A), the log toggle (fit coordinate; keeps A and K positive), and optional natural-unit lower and upper bounds. Initial values come from the Network workspace.
• Optimizer: Levenberg-Marquardt is the default. Bounded scalar (golden-section search) is offered when exactly one parameter has finite lower and upper bounds; the objective must be unimodal between the bounds. Its final bracket is a numerical search diagnostic, not an uncertainty interval, and a bound can be the fitted value. Covariance, standard errors and linearized intervals are reported as unavailable for this method.
• A converged joint fit is a local least-squares optimum, not a guaranteed global one. "Apply fitted values to the network" is enabled only after a converged fit without errors and is undoable.
• Bootstrap assumptions: independent errors with constant variance within each species trace, and a fixed design. Failed refits are counted with their reasons. The percentile intervals carry no coverage guarantee and are never replaced by the linearized intervals of the base fit. Noisy data can make many refits fail to converge.
• Global indices are Monte Carlo estimates: they are not clipped to 0..1 and no confidence interval is given for them. Zero output variance makes them undefined.
• SBML import (Inference > Mechanism, or the Network workspace): Level 3 Version 2 Core only, one constant compartment in litres, concentration species, constant parameters with declared units, irreversible elementary reactions with monomial rate laws and integer stoichiometry. Rules, events, assignments, modifiers, reversible or non-elementary laws, annotations and extensions are refused with a message. Files are limited to 2 million characters. Enter the reference temperature yourself: imported rate constants are used at that temperature with zero activation energy. Preview the counts and warnings, then replace the network (Undo restores it) or open the model as a new document.
• Sparse assembly: formation rates and the material Jacobian in compressed sparse rows at the initial concentrations and one temperature, with the matrix size, nonzeros and an estimated memory figure; up to 2000 species, 10000 reactions and 128 MiB estimated. It is a diagnostic only: there is no large-mechanism transient solve. The Jacobian triplets and formation rates export as CSV.

Sizing workspace: Levenspiel plots and reactor combinations

For a key reaction and key reactant the tool tabulates -r_A(X) from the network and plots F_A0/(-r_A) against conversion. The CSTR volume is the rectangle F_A0 X/(-r_A(X)); the PFR volume is the area under the curve. It also gives N equal CSTRs in series, and the CSTR-then-PFR split that minimises the total volume (a CSTR up to the point of maximum rate, then a PFR, for autocatalytic kinetics).

• Liquid: C_i = C_i0 + (nu_i/|nu_A|) C_A0 X. Gas at constant T and P: divided by 1 + eps X, eps = y_A0 sum(nu)/|nu_A|.
• Adiabatic sizing computes T(X) from the energy balance; the plot then shows the characteristic maximum of an exothermic reversible reaction when the reaction is reversible.
• Multiple reactions: the plot uses the rate of the chosen reaction with the other reactions ignored. Use the Reactor workspace for full networks. Sizing rejects targets beyond limiting-reactant exhaustion or equilibrium. It requires a positive removal rate over the full conversion path; a conservative interval check refuses paths it cannot certify within its subdivision budget.

Fit workspace: rate laws from data

Import data with "Import CSV file" or paste text. Delimiters (comma, semicolon, tab, space), decimal commas with semicolon files, a header row, comment lines starting with # and a byte-order mark are handled; malformed rows are reported but kept. Cells of the table can be edited.

• Confidence intervals are theta +- t(1 - alpha/2, df) se, with covariance s^2 (J^T J)^-1 at the solution (linearised, so they are approximations for strongly nonlinear problems). With no degrees of freedom they are undefined and reported as such.
• Kinetic fits are scaled by each species' largest observed value so a major and a minor species weigh equally.
• Local minima: nonlinear fits can need good starting values. The Marquardt solver reproduces the NIST certified values from the recommended start 2 of all twelve tested datasets and from start 1 of nine; it does not converge from start 1 of BoxBOD, MGH10 and Eckerle4, which are known to be hard. If the result looks wrong, try other starting values and compare the residual plot.
• The differential method amplifies noise; prefer the integral method or a kinetic fit for noisy data.

Yield workspace: selectivity and yield for multiple reactions

• Conversion X = (n_A0 - n_A)/n_A0 of the key reactant.
• Yield Y_D = (n_D - n_D0)/n_A0 (moles of desired product per mole of key reactant fed). The fractional yield multiplies by the stoichiometric ratio so it lies between 0 and 1.
• Overall selectivity S = (n_D - n_D0)/sum(n_U - n_U0). Instantaneous selectivity is the ratio of the formation rates r_D/r_U along the trajectory.
• The optimum scan varies end time, volume (at fixed flow) or temperature and refines the maximum yield by golden-section search. For A -> B -> C it reproduces t* = ln(k1/k2)/(k1 - k2) in a batch/PFR and tau* = 1/sqrt(k1 k2) in a CSTR.

RTD workspace: residence time distribution basics

Tanks in series (E(theta) = N^N theta^(N-1) e^(-N theta)/Gamma(N), N may be non-integer) and the axial dispersion model (open-vessel E curve; closed-vessel Danckwerts solution for first-order conversion). The panel compares the conversion of a first-order reaction for plug flow, N tanks, dispersion and a single CSTR. The RTD analysis accepts 1 <= N <= 500, 1e-12 <= Pe <= 1e12 and 0 <= k tau <= 1e12; values outside this numerical domain are refused. The engine also provides tracer-curve moments, N and Pe estimation, and a segregation model for a network.

Files, exports and reports

• Document: .ratelab.json (format "ratelab", version 1) containing the network, reactor, data sets and settings, plus a copyright and terms notice. Opening validates the structure and refuses foreign or newer files with a message.
• Autosave to this browser after each edit: small documents in local storage, large ones (for example imported mechanisms) in the browser database after a free-space check. The footer shows the autosave state; in private browsing or with full storage autosave pauses and Save (Ctrl+S) still works.
• Inference settings (shared parameters, experiments, sensitivity design, optimizer and bootstrap settings) are stored in the optional field fit.inference of the same version-1 document (schema 1). Older documents without it open with defaults; documents that never use the Inference workspace are written unchanged, and the optimizer is stored only when it is not the default.
• CSV: concentration profiles, steady states, fit parameters, Levenspiel data, data sets, sensitivity tables, joint-fit parameters, bootstrap samples, sparse Jacobian triplets and formation rates; each file starts with comment lines carrying the footer.
• CSV text containing line breaks, including Unicode line and paragraph separators (U+2028/U+2029), is quoted within its cell. Project titles in comment lines have line breaks replaced by spaces. Formula-leading text is prefixed with an apostrophe; numeric values keep their numeric representation.
• SVG: every plot has an SVG button; the file includes the footer line.
• Report workspace: Markdown download, print/PDF through the browser and the built-in model checks.
• Every export ends with "Made with Ratelab · simulations4all.com".

Keyboard shortcuts

Limitations: what the tool does not do

• Ideal reactors only: perfect mixing or plug flow, no pressure drop, no heat or mass transfer limitations, no catalyst pellet or interphase effects.
• Liquid models assume constant density; gas models assume an ideal gas at constant pressure. Heat capacities are constant.
• Gas transients, gas recycle, gas CSTR stability and gas multiplicity searches are unavailable. Gas CSTR steady solving returns one root from one Newton start. Time-varying feeds and non-ideal reactor networks beyond tanks in series are not offered.
• Reaction rates are concentration-based (no activity coefficients); equilibrium constants are in mol/L units.
• Nonlinear fits report numerical failure for nonfinite residuals or Jacobians, and stagnation when no downhill step satisfies a convergence criterion. Kinetic parameter confidence intervals are linearised; strongly correlated parameters (A and Ea over a narrow temperature range) have wide, correlated intervals.
• Compared with desktop kinetics packages, the tool focuses on small ideal-reactor models. Inference covers isothermal batch concentration kinetics only. SBML import is a strict subset and there is no SBML export. Sparse Jacobian assembly is a diagnostic: there is no sparse stiff integration, and the Reactor workspace refuses networks above 150 species (a conservative browser ceiling for its dense integrator).
• Residual bootstrap requires a converged base fit and withholds intervals if too many refits fail; conservative stopping can reject near-optimum noisy fits. Available numerical checks do not establish laboratory interval coverage.
• Textbook worked examples are listed as "pending source" until their numbers are keyed from a legitimate copy; they are not counted as passes.

Troubleshooting

How we verify this tool

The Verify view runs the tool's own reference suite in your browser, case by case, with progress, and shows for each case what is checked, the reference with its citation, the computed value, the difference, the tolerance and PASS or FAIL. Some comparisons recompute the same formula and check transcription only; separate independent tests are documented in docs/RIGOR_REGISTER.md. The same cases (engine/verification/cases.ts) are run by the automated test suite, so what you see is what CI checks.

• Closed-form solutions: first, second and fractional order, consecutive reactions (Bateman), reversible, parallel, CSTR and PFR design equations, gas-phase volume change, semibatch, recycle, energy-balance invariants, Levenspiel sizing, tanks in series and dispersion.
• Stiff reference solutions: the Robertson (ROBER), HIRES, Oregonator and van der Pol problems, with endpoint values generated by this project (SciPy Radau, cross-checked with a second tolerance, BDF and LSODA, plus mpmath for HIRES only; only the digits all methods agree on are stored). They agree with the published reports of the Test Set for IVP Solvers (Mazzia and Magherini, University of Bari), which is cited as an independent comparison, not as the source.
• NIST Statistical Reference Datasets (StRD) for nonlinear regression: certified parameters, standard deviations and residual sums of squares to six significant digits. The datasets are U.S. Government data from the National Institute of Standards and Technology (itl.nist.gov/div898/strd); NIST does not endorse this tool.
• Reference computations using SciPy (SciPy and its numerical dependencies are BSD-3-Clause; solve_ivp Radau at rtol 1e-13, curve_fit, least_squares, linregress, t quantiles, gamma distribution) for non-isothermal, gas-phase, semibatch and fitting cases. They were run offline and only the resulting numbers are recorded; no SciPy code is shipped. The generator script is included. A separate language alone does not establish independence; copied formulas and matching trapezoid rules are classified as same-formula.
• Sanity checks on your own model (Report workspace): analytic Jacobian against finite differences, positivity, stoichiometric invariants, tolerance refinement and agreement of the two integrators.
• Cases that depend on a textbook example are marked PENDING SOURCE and never counted as passes.