Computational chemistry: methods, inputs, and interpretation

Use Grid to connect physical assumptions, calculations, and interactive inputs in a saved model. A computed number is useful only when its method, units, and applicability are clear. The examples below use Grid calculations with explicit input contracts.

Start with guarded examples

• Guarded Arrhenius Lab: first-order rates and half-lives, with temperature in kelvin, activation energy in J/mol, and the prefactor in s^-1. At 298.15 K, 75000 J/mol, and 1e13 s^-1, the rate is approximately 0.725384841 s^-1. Changing temperature to 320 K gives approximately 5.724601819 s^-1.
• Guarded Beer–Lambert Mixture: two ideal absorbing species, concentrations in mol/L, path length in cm, fixed absorptivities in L/(mol cm), and dimensionless absorbance. The default concentrations are both 30 micromol/L. The three signals are 0.36, 0.39, and 0.39. LINEST performs the QR regression with no intercept.

The bounds are the examples' declared operating windows, not universal limits on chemistry. VALIDATE ... MESSAGE rejects an invalid input write before it changes the saved model. The Arrhenius example permits negative apparent activation energy. A zero prefactor means no decay and no finite half-life; the half-life output is then #N/A, with an explanation in Interpretation.

The existing ARRHENIUS_RATE and BEER_LAMBERT functions remain algebraic calculators. They do not acquire implicit physical-domain rejection in this change. Callers should state their assumptions and validate inputs. For example, signed baseline-corrected signals may need a different contract from an ideal absorbance model. Do not interpret finite arithmetic as confirmation that a physical model is applicable.

Names resembling cell addresses can be parsed as addresses: use RateWarm or RateAt_320 instead of RateAt320. The address diagnostic identifies the token and suggests including an underscore. Valid addresses keep their meaning. Write a rectangular matrix as [10000, 2000; 5000, 8000; 1000, 12000]; semicolons separate rows. An array of arrays is a different structure. Transpose and multiplication should receive the intended matrix shape rather than rely on implicit flattening.

For dimensional arithmetic, write physical seconds explicitly as Elapsed = 1 INTO unit:s. The literal 1s denotes a duration and evaluates to the string "PT1S"; it is not a physical-unit scalar. Under strict, adding that duration to a numeric length produces a coercion error. Adding a length to explicit unit:s instead produces an incompatible-dimensions diagnostic. The compiler error retains the offending source location so the editor can identify the expression. Correct the model's quantities; turning strictness off does not establish that the physical expression is meaningful.

For recognized literal nested arrays, the compiler's GRID_NESTED_ARRAY_TRANSPOSE advisory explains the outer dimensions and gives a semicolon-row example. It does not reject an intentional nested-container transpose, even under strict dimensional checking. The canonical chemistry-matrix-authoring.grid example puts both representations beside a valid spectroscopic mixture calculation. Open the model diagnostics or the affected cell's checks to read the hint. Array elements supplied through references or calls can have unknown kinds; the compiler leaves those numeric matrix shapes unproven. It does not execute the model to guess them.

Read an ODE result and compare numerical controls

Use ODE_REPORT((time,state) => Rates(time,state), initial, start, end, {format: "record", method: "auto", rtol: 1e-8, atol: 1e-12}) to request a readable result. The ODE entry point expects a two-argument lambda; wrap a named function as shown. Omit format or use "row" to retain the existing numeric diagnostics row.

Select the report or open its popout to see the actual method, whether automatic detection switched methods, local error controls, accepted/rejected steps and terminal components. Expand Numerical work for the other counters. The complete report and copy action preserve original precision. Read Report.state for downstream calculations; inspecting or copying the report does not request another integration. State names and units belong to the authored model.

The canonical chemistry-ode-reports.grid workflow uses the synthetic Robertson reaction benchmark over 0–100 seconds. It deliberately solves three control settings, authors SUM(Report.state)-1 conservation residuals, and compares terminal populations under tighter tolerances. A small conservation residual can coexist with inaccurate individual populations. Local error controls are not global-error bounds, and the same settings across different methods need not yield the same error. The reference populations in that example apply only at 100 seconds. Reusable ODE_SOLUTION sampling remains linear between stored rows; the report does not change that interpolation contract.

Read CHEM_PROPERTIES as a portable graph method

CHEM_PROPERTIES(molecule) returns the existing numeric fields plus a provenance object:

Field	Meaning for the current portable calculation
method	grid_portable_graph_proxy
method_version	1, identifying the conventions below
calibrated	false
lipinski_assessment	proxy_derived
applicability	An explanation that these are exploratory descriptors
units.molecular_weight	g/mol
units.topological_polar_surface_area	angstrom^2
units.estimated_log_p	dimensionless

The cell inspector displays the proxy status, units, and proxy-derived Lipinski flags. The full record remains available through the existing expanded view and JSON/API output. A legacy record without provenance is visibly marked as having unavailable method provenance; an unknown method is not presented as calibrated.

Version 1 has these conventions:

• formula uses the molecular graph and inferred hydrogens. heavy_atoms excludes hydrogen. molecular_weight sums the portable element masses for explicit atoms and inferred hydrogens; it is not an exact isotopic mass.
• Donors are nonnegatively charged N/O/S atoms with explicit or inferred hydrogen. Acceptors use portable graph rules: positively charged atoms are excluded; O/S are counted; N attached to carbonyl carbon is excluded; halogens are counted only when negatively charged. These rules are not a promise of agreement with another toolkit's acceptor definition.
• Polar surface area is an atom-contribution proxy: nonpositive N contributes 12.03, positive N 27.64, neutral/nonnegative O 17.07, negative O 40.13, S 25.30, and P 38.80 square angstroms. Other elements contribute zero.
• The log P proxy is `1.46C + 1.23halogens - 1.5heteroatoms - 0.35donors
  • 0.15*rings`; heteroatoms exclude carbon and hydrogen. It is neither Crippen nor XlogP3.
• rotatable_bonds counts single bonds whose endpoints both have graph degree greater than one. It does not apply a calibrated toolkit's complete exclusions for ring and amide bonds. Explicit hydrogen representation can affect graph-degree-based counts.
• Ring counts use Grid's bounded graph ring perception. fraction_csp3 is the fraction of carbon atoms that are nonaromatic and have only single incident bonds. net_formal_charge sums authored atom formal charges.
• lipinski_violations counts the existing thresholds: mass >500, donors >5, acceptors >10, and the proxy log P >5. It is a proxy-derived flag count, not an established calibrated screening assessment.

For example, the portable aspirin log P proxy is 6.94 and triggers a flag. That value should not be substituted for a named calibrated method. Grid's existing calibrated-properties operation accepts named methods through a configured property adapter and retains method/execution provenance. Request that operation explicitly when the assessment requires it. A missing adapter must produce an unavailable error rather than silently return a proxy. This disclosure change does not install or automatically invoke an adapter.

The change is additive. Existing numeric fields keep their names and meaning; consumers comparing an entire JSON object must allow the new provenance field. Native deserialization of an older portable property record supplies the known portable-method disclosure while preserving its numeric values. Raw archived JSON is not rewritten automatically. No claim of experimental validation follows from adding method metadata.

Calculate properties with a named method

In a saved workbook, open a Molecule surface and import a SMILES or SDF file. Select its molecular artifact, choose Calculate calibrated properties under Scientific operation, and choose a Property method:

Choice	Requested calculation
RDKit descriptor set	Crippen log P, fragment polar surface area, and molecular descriptors
Crippen log P	Log P and molecular descriptors; polar surface area is not requested
Fragment polar surface area	Polar surface area and molecular descriptors; log P is not requested

The workflow checks whether a healthy property adapter is registered when you select the operation. It checks again only when you choose Check availability. Registration reports a broad capability; the job confirms that the selected method is supported and permitted by the runtime's configuration. If the adapter is unavailable, configure the existing optional property adapter before using this workflow. The interface neither installs an engine nor substitutes the portable graph proxy for an unavailable method. The required adapter must already be configured in this installation.

Calculate properties runs the selected method on every molecule in the artifact through the existing model job API. Batch progress counts completed molecules out of the selected total; it is not an estimated remaining time. Cancellation and failure messages use the same job controls as other molecular operations. A successful job saves an analysis artifact and opens its results. Reopening that artifact reads the saved results; it does not repeat the calculation or require the adapter to remain available.

Results show at most 50 molecules per page, in source order, with units, backend/version, toolkit/applicability text, and method warnings. Not reported means the result did not provide that descriptor; it never means zero. The bundled RDKit adapter does not supply log S or pKa. Expand Execution provenance and complete result to inspect the retained method, executable and input/output digests, and reproducibility class. Download full artifact (JSON) includes the full result and its provenance, including molecules outside the current page. The compact display uses up to 10 significant digits; expanded and downloaded results preserve the original numeric values. An inconsistent method or execution record is identified rather than presented as a verified method result.

The bundled adapter preserves explicitly authored hydrogen atoms. Counts such as rotatable bonds can therefore differ from a toolkit workflow that removes those hydrogens before calculating descriptors. Results with explicit hydrogens include a warning; use the same hydrogen convention when comparing methods.

For a small comparison, save the following as property-method-comparison.smi and import it. The repository also includes it under examples/chemistry/.

CC(=O)Oc1ccccc1C(=O)O aspirin
c1ccccc1 benzene
CCO ethanol
CC(=O)O acetic_acid

It contains aspirin, benzene, ethanol, and acetic acid in that order. The independent RDKit 2026.03.6 reference gives aspirin Crippen log P 1.3101 and benzene 1.6866. These differ substantially from Grid's portable graph proxies 6.94 and 8.91; choosing a named method makes the distinction explicit. Agreement with RDKit establishes agreement with that implementation, not experimental validation or a complete drug-screening assessment.

Recover from nonlinear solver errors

CURVE_FIT and NSOLVE preserve their error codes and now carry explanations through the resident result, public typed JSON, and inspector. For a fit with two observations and three free coefficients, #VALUE! explains that there are more parameters than data points and suggests adding observations or reducing free parameters. Malformed vectors, initial guesses, tolerances, and iteration counts identify the offending argument contract.

Numerical failures remain #CALC!, with separate explanations for an invalid initial model evaluation, a singular numerical system, and nonconvergence. Successful values and stopping conditions are unchanged. IFERROR, ISERROR, and code-based handling retain their meanings. API consumers must inspect returned cell values; HTTP success does not imply every cell succeeded.

A successful fit still needs residual analysis, parameter identifiability, and an appropriate uncertainty model before experimental interpretation. These examples do not establish calibrated molecular mechanics, production MD, or electronic-structure accuracy.

Fit observations and inspect the result

Use CURVE_FIT.REPORT when you need to interpret a fitted model. It returns the same coefficients as CURVE_FIT with an explicit report. Select that result in the cell inspector or expand the cell to read coefficients, the stopping reason, residual scatter, local rank, and conditioning. Observation tables show 50 rows at a time; the complete result retains original precision.

# Deterministic noisy observations; x and response use the example's own scales.
A1 = CURVE_FIT.REPORT(
  (x, slope, intercept) => slope*x+intercept,
  {0,1,2,3,4}, {1.1,2.9,5.1,6.9,9}, {0,0}, 1e-12
)
A2 = INDEX(A1.parameters,1,1)
A3 = A1.ssr
A4 = A1.jacobian.rank

This example fits slope approximately 1.98 and intercept 1.04, with SSR 0.036. RMSE divides SSR by all five observations; residual standard error uses the three residual degrees of freedom. Residuals are fitted minus observed. A small parameter step can stop the fit even when the gradient exceeds the requested tolerance. Read the reported stopping reason instead of treating converged as a statement about every accuracy criterion.

The adsorption starter uses NIST's Misra1a observed dataset. Compare its two documented starting guesses and inspect the observation/fit and residual plots. It estimates capacity about 238.942129 and the original rate coefficient about 0.000550156432. NIST labels the variables pressure and volume without giving measurement units; this example preserves that limitation.

Save the initial model state, try another initial guess, and set the iteration budget to 1 to inspect a clear failure. Restore 1000 to recover. Reopening a model with the new function requires a runtime that supports it; older installed runtimes are not updated by adding this example.

This unweighted report uses equal weights and no constraints. Input validation on an initial guess does not constrain subsequent trial parameters. Rank deficiency means some parameters cannot be distinguished locally; change the model or obtain more informative data before interpreting individual estimates. Large rank analysis can be omitted explicitly, and conditioning depends on parameter scales. Reports without explicit uncertainty options omit parameter confidence intervals. The next section shows how to request them. LINEST(..., TRUE, TRUE) and REGRESS already provide linear-model diagnostics/inference, but their outputs must not be relabeled as nonlinear-fit uncertainty.

Request local parameter intervals

For observations reasonably described by independent normal errors with the same unknown variance, explicitly request local uncertainty:

A1 = CURVE_FIT.REPORT(
  (x, slope, intercept) => slope*x+intercept,
  {0,1,2,3,4}, {1.1,2.9,5.1,6.9,9}, {0,0}, 1e-12, 1000,
  {uncertainty: "local_iid", confidence: 0.95}
)
A2 = A1.parameter_uncertainty.standard_errors
A3 = A1.parameter_uncertainty.lower
A4 = A1.parameter_uncertainty.upper

The canonical chemistry-decay-intervals.grid example applies this option to a synthetic exponential-decay calibration whose covariance and bounds were checked against an independent reference.

The report shows approximate individual 95% intervals alongside coefficients. It estimates a common observation variance from residuals and uses a local linear approximation to the model. Ordinary reports still omit uncertainty. Inspect the noise assumptions before selecting this method; equal weights alone do not establish equal observation variance.

A stopped fit can have unavailable intervals. The report explains deficient rank, missing residual degrees of freedom, zero residual variance, unavailable derivatives or insufficient numerical stationarity. Review model design, scaling and starting guesses. Increasing an iteration budget cannot repair uninformative observations or an unsuitable statistical model.

These intervals can fail badly for weakly identified or strongly nonlinear models. A retained 1,000-trial weak-design decay simulation had many solver failures and only 34.6% unconditional coverage for its baseline parameter, despite requesting nominal 95% intervals. Even among returned intervals, baseline coverage was approximately 64%. In contrast, the tested well-supported linear/decay designs had 94.8–96.2% empirical individual-parameter coverage. Those are results for specific simulated data families, not a general guarantee. Use a simulation matched to your experiment, and consider a different model or uncertainty method when local intervals are inadequate.

Fit observations with unequal precision

Use the canonical chemistry-weighted-decay.grid example to compare two assumptions on the same synthetic decay. standard_deviations supplies known observation errors in response units; weights supplies relative influence. Do not substitute estimated instrument precision for known errors without accounting for that extra uncertainty.

Report = CURVE_FIT.REPORT(
  (time, slope, intercept) => slope*time+intercept,
  [0,1,2], [1,2,6], [0,0], 1e-12, 200,
  {standard_deviations: [1,0.5,1], uncertainty: "local_known"}
)

This weights the middle observation four times as strongly as the others. The report distinguishes raw residuals and RMSE from the standardized objective Σ(residual/σ)², and shows each supplied σ beside its residual. The result view names the actual noise model. Known-error local normal intervals use the supplied errors without estimating a new scale from the residuals; even a perfect fit can have uncertainty.

For relative errors, use {weights: [1,4,1], uncertainty: "local_relative"}. The coefficients and objective are the same here, but Student-t intervals estimate a common variance scale from weighted residuals. Omitting uncertainty returns the weighted fit without intervals. Supply either weights or standard deviations, with positive finite entries matching the observations or one positive scalar for all observations. Mismatched methods and unsupported options produce recovery guidance. Without explicit bounds parameters remain unconstrained.

Local intervals still need informative observations and a suitable statistical model. Known errors do not make nonlinear confidence coverage exact. Inspect rank, stationarity, residual patterns and the declared assumptions before using individual parameter bounds.

Compare an authored parameter limit

The canonical chemistry-bounded-adsorption.grid example fits the NIST Misra1a pressure/volume observations with a capacity cap of 220, then compares an unconstrained fit of the same data. The cap is a sensitivity assumption introduced by the example. It is not a reported experimental constraint or NIST's certified target.

Report = CURVE_FIT.REPORT(
  (time, slope, intercept) => slope * time + intercept,
  [0, 1, 2], [1, 2, 6], [0, 1], 1e-12, 200,
  {lower: [0, 1], upper: [BLANK, 1], standard_deviations: [1, 0.5, 1]}
)

This fits a nonnegative slope while fixing the intercept at 1. Endpoints follow parameter order after the observation variable. BLANK leaves an endpoint unbounded; a scalar broadcasts to every parameter. Initial values must be feasible, and fixed coordinates must start at their exact authored value. The bounded operation supports up to 64 parameters and 262144 Jacobian entries.

Inspect the coefficient table's limits and active status, the raw residuals, and the feasible-gradient check. An estimate at a bound can be the correct constrained answer even when its ordinary residual gradient is nonzero. “Stopped” means another numerical stopping condition held before feasible stationarity met the requested tolerance. It should prompt a review of scales, starting values and model assumptions. Neither status proves a global optimum.

Compare the constrained and unconstrained residual patterns and loss before interpreting the parameters. Bounds can encode useful prior physical knowledge, but an incorrect cap can bias a rate or baseline. Fixed values remain assumptions; nominal residual degrees of freedom subtract the nonfixed parameter count.

Local confidence intervals are unavailable for constrained fits. A matching local uncertainty request is retained and explicitly declined; ordinary local covariance does not account for bounds. The report does not turn a numerically precise boundary estimate into a claim of scientific certainty.

Resample a fit with declared observation noise

The bootstrap decay example uses uncertainty:"bootstrap_normal", an explicit integer seed, and resamples:400 for individual 95% percentile intervals. The seed reproduces random draws; it does not establish a physically correct noise model. Supply known observation standard deviations only when justified. Otherwise, equal variance or relative weights estimate a common scale from residuals.

Select the report to inspect seed, requested/attempted/accepted/failed refits, bootstrap spread and intervals. Each simulated dataset starts at the authored initial parameters and retains the objective, bounds and solver controls. Any failed or numerically ineligible refit makes intervals unavailable. The complete report retains all outcomes and failure categories, without silently replacing failures. Zero fitted scatter cannot estimate unknown noise.

Compare the freely estimated amplitude with the example's fixed-amplitude scenario. The latter's rate interval is conditional on amplitude exactly 2; the blank amplitude interval does not mean its experimental value is certain. Inspect assumptions, residual patterns and stopping reasons before interpreting narrower limits. Percentile intervals are neither simultaneous nor predictive.

Resampling does not repair weak designs automatically. In the retained 500-dataset experiment with five observations and residual-estimated noise, requested 95% percentile coverage was only 83.8% for slope and 82.4% for intercept. For a locally linear model, compare local Student-t intervals; collect more informative observations before treating a narrow interval as strong scientific evidence. These simulation percentages apply to that design, not every chemistry dataset. See the increment-nine investigation for complete seeds, controls, unavailable outcomes and Monte Carlo uncertainty.

Default count is 1000. Requests allow 100–5000 resamples and at least ten expected draws per confidence tail; 95% therefore needs at least 400. Larger models have additional explicit work limits. No count is silently reduced. The method is parametric normal resampling; nonparametric, BCa and studentized bootstrap methods are not implemented. See CURVE_FIT.REPORT in the function reference for its signature and options.

Comparing fits with the same success criterion

For an unweighted, unconstrained fit with no more than 64 parameters, add {stopping: "gradient"} as argument seven of CURVE_FIT.REPORT after an explicit tolerance and iteration limit. Use 1e-7, 1000 for the retained noisy-decay and NIST comparison. This requires the unscaled infinity norm of J^T*(fitted-observed) to be strictly below the tolerance. A tiny step alone cannot produce a successful report. Add uncertainty: "local_iid" in that same record if the stated observation-error assumptions apply.

The matching SciPy reference uses trust-region reflective least squares with linear loss, no bounds, x_scale=1, ftol=None, xtol=None, and gtol=1e-7. These settings match successful stopping, while iteration and evaluation ceilings remain different work limits. Existing formulas without this option keep their previous behavior. Agreement is numerical evidence; it does not establish faster workflows or better participant outcomes.

The molecular result panel’s Download full artifact (JSON) action reads all pages of the selected immutable result and includes both the full result array and provenance record. It preserves original numeric precision. An incomplete or inconsistent response produces an error rather than a partial download. The metadata-only artifact endpoint is not a complete result export.