Validation¶
PQSetup separates local checks, environment discovery, and PQ parser validation. The interface states which layers actually ran.
Local preflight¶
Local checks run while the setup is edited. They cover:
readable structure data, finite coordinates, and known elements;
periodic-cell geometry and PQ’s centered wrapping convention;
unusually close atom pairs using ASE covalent radii;
ensemble and coupling parameters, including the temperature ramp;
required calculator, topology, parameter, template, and molecule-descriptor files;
advanced keywords against PQ’s parsers: option lists, bounds and the combinations PQ rejects (for example Hubbard derivatives without third order, a reaction field without
rf_epsilon, or M-SHAKE without its geometry file);restart names and generated-input consistency.
Only settings that are visible on the page reach the input. Values you typed under a hidden control — a manostat after switching back to NVT, MM constraints after switching to QM — are remembered for when you return, but never written.
The close-contact scan is a bounded geometric heuristic. It reports up to 200 contacts and does not establish bonding, protonation, or chemical correctness.
Environment discovery¶
pqsetup doctor and the Method section inspect PQ and supported external
calculators. A detected executable means that the command or package was found
and its setup appears complete enough for input generation.
Discovery does not run a reference energy, force, or dynamics calculation. Warnings may therefore accompany an export that is intended for another machine.
PQ parser validation¶
When a selected PQ executable advertises validation schema v1, PQSetup calls PQ’s own parser:
Context |
Scope |
Purpose |
|---|---|---|
Package preview and export |
|
Check syntax and release-level input support without requiring the local calculator |
|
|
Check syntax and the capabilities of the installed PQ build |
PQSetup discovers this support through PQ --capabilities=json. Builds
without the contract continue to receive local checks, and the missing PQ
validation is reported explicitly.
Read the result¶
An error is a known problem with the setup or generated package and blocks
export. A warning needs review but permits export; warnings are recorded
in pqproject.json. Unavailable means a validation layer did not run,
for example because PQ is not installed locally. It is not a pass or a claim
that PQ will accept the input.
When moving a package to another machine, check that machine with
pqsetup doctor and validate the generated inputs there if its PQ build
supports the parser contract. The local preflight cannot check a calculator
that is only installed on the destination machine.
What validation does not prove¶
Passing preflight does not prove:
that the model chemistry or force field is appropriate;
that the timestep and coupling constants are stable;
that equilibration or sampling is long enough;
that the vacuum or periodic cell is converged;
that the structure has the intended bonding, charge, spin, or protonation;
that a detected calculator will produce scientifically meaningful results.
Treat every default as a starting template. Review the generated inputs and test the protocol on the intended execution environment.
Validate an existing input¶
pqsetup validate run.in
Use --json for structured diagnostics:
pqsetup validate --json run.in
An explicitly configured but unusable PQ executable is an error. A PQ build that does not advertise installed validation produces a warning after local checks.