Outputs and Provenance

The CLI supports three output formats:

text
JSON
CSV

Units

Output units can be selected with:

--output-units <kt|kcal|kj>

The CLI converts the reported free energy and uncertainty from reduced units into the selected output unit using the requested temperature.

Text output

Text output is intended for direct reading in the terminal.

It includes:

delta_f
uncertainty
lambda endpoints, which are scalars for one-dimensional schedules and vectors for multidimensional schedules
lambda_components when available
sample counts
u_nk_observable when relevant
ti_method when the estimator is TI
ti_method_reason when TI method auto-selection was used
overlap summary when requested

For nes, the scalar result still follows the same shape, but windows, samples_in, and samples_kept all count switching trajectories rather than equilibrium windows or samples.

JSON output

JSON output is suitable for shell pipelines and downstream tooling.

The payload contains:

the scalar result fields
optional overlap summary
a provenance object

from_lambda and to_lambda are encoded as:

numbers for one-dimensional schedules
arrays for multidimensional schedules

CSV output

CSV output appends provenance fields after the result columns so the row remains self-describing.

For multidimensional schedules, the endpoint columns are emitted as quoted bracketed vectors such as "[0;0;0.8]".

Provenance

In this project, "provenance" means the analysis settings and sample-count metadata that explain how a reported result was produced.

Current provenance fields include:

estimator name
temperature
whether decorrelation ran
fixed-count burn-in trimming
whether auto-equilibration ran
the effective fast value
the effective conservative value
nskip
u_nk_observable when applicable
ti_method for TI results
ti_method_reason when ti --method auto selected the integration method
lambda_components when the parser can identify named lambda dimensions
number of windows
number of samples before preprocessing
number of samples after burn-in trimming / auto-equilibration
number of retained samples after decorrelation

This matters because preprocessing choices directly change the data used by the estimators.

Example JSON payload

{
  "delta_f": -113.58,
  "uncertainty": 1.17,
  "from_lambda": [0.0, 0.0, 0.8],
  "to_lambda": [0.0, 0.0, 0.9],
  "units": "kT",
  "overlap": {
    "scalar": 0.0183,
    "eigenvalues": [1.0, 0.9817]
  },
  "provenance": {
    "estimator": "mbar",
    "temperature_k": 300.0,
    "decorrelate": true,
    "remove_burnin": 0,
    "auto_equilibrate": false,
    "fast": false,
    "conservative": true,
    "nskip": 1,
    "u_nk_observable": "de",
    "lambda_components": ["mass-lambda", "coul-lambda", "vdw-lambda"],
    "windows": 15,
    "samples_in": 300,
    "samples_after_burnin": 300,
    "samples_kept": 126
  }
}

Keyboard shortcuts