oqp.utils.oqp_input =================== .. py:module:: oqp.utils.oqp_input .. autoapi-nested-parse:: .. code-block:: text 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 ---------- .. autoapisummary:: oqp.utils.oqp_input.GENERIC_SCHEMA_KEYS oqp.utils.oqp_input.ROUTE_DRIVER_SCHEMA_KEYS oqp.utils.oqp_input.LEGACY_ONLY_SCHEMA_KEYS oqp.utils.oqp_input.INTENTIONALLY_FORBIDDEN_SCHEMA_KEYS oqp.utils.oqp_input.SCHEMA_KEY_OWNERS oqp.utils.oqp_input.OQP_SCHEMA_KEYS oqp.utils.oqp_input.DRIVER_OPTIONS Exceptions ---------- .. autoapisummary:: oqp.utils.oqp_input.OQPInputError Classes ------- .. autoapisummary:: oqp.utils.oqp_input.StateRef oqp.utils.oqp_input.CallSpec oqp.utils.oqp_input.CalculationSpec oqp.utils.oqp_input.OQPResolution Functions --------- .. autoapisummary:: oqp.utils.oqp_input.looks_canonical oqp.utils.oqp_input.parse_canonical_oqp oqp.utils.oqp_input.lower_to_legacy oqp.utils.oqp_input.render_canonical_oqp oqp.utils.oqp_input.compile_natural_request oqp.utils.oqp_input.resolve_oqp_text oqp.utils.oqp_input.resolve_oqp_file Module Contents --------------- .. py:exception:: OQPInputError Bases: :py:obj:`ValueError` .. code-block:: text Raised when semantic input is ambiguous, contradictory, or invalid. .. py:class:: StateRef .. code-block:: text 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. .. py:attribute:: label :type: Optional[str] :value: None .. py:attribute:: root :type: Optional[int] :value: None .. py:property:: multiplicity :type: Optional[int] .. py:property:: physical_index :type: Optional[int] .. py:class:: CallSpec .. code-block:: text A driver or section-style call from canonical input. .. py:attribute:: name :type: str .. py:attribute:: args :type: Tuple[Any, Ellipsis] :value: () .. py:attribute:: kwargs :type: Mapping[str, Any] .. py:attribute:: explicit :type: bool :value: True .. py:class:: CalculationSpec .. code-block:: text Parsed, implementation-independent calculation request. .. py:attribute:: model :type: str .. py:attribute:: functional :type: str .. py:attribute:: basis :type: str .. py:attribute:: model_options :type: Mapping[str, Any] .. py:attribute:: options :type: Mapping[str, Any] .. py:attribute:: driver :type: CallSpec .. py:attribute:: modifiers :type: Tuple[CallSpec, Ellipsis] .. py:attribute:: source_text :type: str :value: '' .. py:property:: reference_method :type: str .. py:property:: reference_multiplicity :type: int .. py:property:: physical_method :type: str .. py:class:: OQPResolution .. code-block:: text Result of classifying, compiling, reparsing, and lowering an input. .. py:attribute:: spec :type: CalculationSpec .. py:attribute:: canonical_text :type: str .. py:attribute:: legacy_config :type: Mapping[str, Mapping[str, str]] .. py:attribute:: was_natural :type: bool .. py:attribute:: source_path :type: Optional[pathlib.Path] :value: None .. py:attribute:: resolved_path :type: Optional[pathlib.Path] :value: None .. py:data:: GENERIC_SCHEMA_KEYS .. py:data:: ROUTE_DRIVER_SCHEMA_KEYS .. py:data:: LEGACY_ONLY_SCHEMA_KEYS .. py:data:: INTENTIONALLY_FORBIDDEN_SCHEMA_KEYS .. py:data:: SCHEMA_KEY_OWNERS :type: Dict[str, Dict[str, str]] .. py:data:: OQP_SCHEMA_KEYS .. py:data:: DRIVER_OPTIONS .. py:function:: looks_canonical(text: str) -> bool .. code-block:: text Return whether malformed text should be treated as canonical, not prose. .. py:function:: parse_canonical_oqp(text: str) -> CalculationSpec .. code-block:: text Parse and semantically validate markerless canonical ``.oqp`` text. .. py:function:: lower_to_legacy(spec: CalculationSpec, *, source_dir: Optional[pathlib.Path] = None) -> Dict[str, Dict[str, str]] .. code-block:: text 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. .. py:function:: render_canonical_oqp(spec: CalculationSpec) -> str .. code-block:: text 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. .. py:function:: compile_natural_request(text: str) -> CalculationSpec .. code-block:: text 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. .. py:function:: resolve_oqp_text(text: str, *, source_path: Optional[pathlib.Path] = None, write_resolved: bool = False) -> OQPResolution .. code-block:: text 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. .. py:function:: resolve_oqp_file(path: pathlib.Path, *, write_resolved: bool = True) -> OQPResolution .. code-block:: text Read and resolve a ``.oqp`` file without changing legacy ``.inp`` files.