oqp.utils.oqp_input

Semantic ``.oqp`` input parser and deterministic request compiler.

The existing INI-style ``.inp`` reader remains the execution format used by
the native/Python layers.  This module adds a small, user-facing language that
describes *physical* methods and states and lowers them to that legacy format.
In particular, users request ``mrsf ... opt(S0)``; they do not need to know that
OpenQP represents the MRSF singlet ground state as response root 1 on top of a
triplet ROHF reference.

This module deliberately uses only the Python standard library.  It can be
loaded before :mod:`oqp` initializes the native library, which is useful for
CLI pre-processing and lightweight editor/web validation.

Attributes

`GENERIC_SCHEMA_KEYS`
`ROUTE_DRIVER_SCHEMA_KEYS`
`LEGACY_ONLY_SCHEMA_KEYS`
`INTENTIONALLY_FORBIDDEN_SCHEMA_KEYS`
`SCHEMA_KEY_OWNERS`
`OQP_SCHEMA_KEYS`
`DRIVER_OPTIONS`

Exceptions

OQPInputError

Classes

`StateRef`
`CallSpec`
`CalculationSpec`
`OQPResolution`

Functions

`looks_canonical`(→ bool)
`parse_canonical_oqp`(→ CalculationSpec)
`lower_to_legacy`(→ Dict[str, Dict[str, str]])
`render_canonical_oqp`(→ str)
`compile_natural_request`(→ CalculationSpec)
`resolve_oqp_text`(→ OQPResolution)
`resolve_oqp_file`(→ OQPResolution)

Module Contents

exception OQPInputError

Bases: ValueError

Raised when semantic input is ambiguous, contradictory, or invalid.

class StateRef

A physical state label, or an explicit implementation root.

``root=N`` is intentionally available for SF-TDDFT, whose spin-adapted
physical state labels cannot be known reliably before diagonalization.

label: str | None = None

root: int | None = None

property multiplicity: int | None

property physical_index: int | None

class CallSpec

A driver or section-style call from canonical input.

name: str

args: Tuple[Any, Ellipsis] = ()

kwargs: Mapping[str, Any]

explicit: bool = True

class CalculationSpec

Parsed, implementation-independent calculation request.

model: str

functional: str

basis: str

model_options: Mapping[str, Any]

options: Mapping[str, Any]

driver: CallSpec

modifiers: Tuple[CallSpec, Ellipsis]

source_text: str = ''

property reference_method: str

property reference_multiplicity: int

property physical_method: str

class OQPResolution

Result of classifying, compiling, reparsing, and lowering an input.

spec: CalculationSpec

canonical_text: str

legacy_config: Mapping[str, Mapping[str, str]]

was_natural: bool

source_path: pathlib.Path | None = None

resolved_path: pathlib.Path | None = None

GENERIC_SCHEMA_KEYS

ROUTE_DRIVER_SCHEMA_KEYS

LEGACY_ONLY_SCHEMA_KEYS

INTENTIONALLY_FORBIDDEN_SCHEMA_KEYS

SCHEMA_KEY_OWNERS: Dict[str, Dict[str, str]]

OQP_SCHEMA_KEYS

DRIVER_OPTIONS

looks_canonical(text: str) → bool

Return whether malformed text should be treated as canonical, not prose.

parse_canonical_oqp(text: str) → CalculationSpec

Parse and semantically validate markerless canonical ``.oqp`` text.

lower_to_legacy(spec: CalculationSpec, *, source_dir: pathlib.Path | None = None) → Dict[str, Dict[str, str]]

Lower physical semantics to a configparser-compatible legacy dict.

Relative geometry/product paths are resolved against the source ``.oqp``
directory rather than the process working directory.

render_canonical_oqp(spec: CalculationSpec) → str

Render stable, readable canonical input that reparses identically.

The route, options, driver, and modifiers are written as separate logical
lines. Geometry is deliberately last; inline coordinates use a
triple-quoted block with one atom per source line. The parser also accepts
the equivalent single-line spelling.

compile_natural_request(text: str) → CalculationSpec

Compile a conservative Korean/English request without an LLM.

Ambiguity is an error.  The caller can show the generated canonical line,
and execution uses a second canonical parse rather than trusting this pass.

resolve_oqp_text(text: str, *, source_path: pathlib.Path | None = None, write_resolved: bool = False) → OQPResolution

Resolve canonical or prose text and optionally write ``.resolved.oqp``.

Natural input is compiled, rendered, and then *reparsed* as canonical input
before it is eligible for execution.  Canonical-looking syntax errors never
fall back to prose interpretation.

resolve_oqp_file(path: pathlib.Path, *, write_resolved: bool = True) → OQPResolution

Read and resolve a ``.oqp`` file without changing legacy ``.inp`` files.