API reference¶
Encoding and decoding¶
qccodec.encode(input_data: Inputs) -> NativeInput
¶
Prepare a complete native invocation for an input without executing it.
Source code in src/qccodec/registry.py
129 130 131 | |
qccodec.decode(program: str, calctype: CalcType | str, *, stdout: str | None = None, directory: Any = None, input_data: ProgramInput | None = None, failed: bool = False, options: Mapping[str, Any] | None = None, version: str | None = None) -> StructuredData
¶
Decode saved program output into structured data without running anything.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
program |
str
|
Name of the program that produced the output. |
required |
calctype |
CalcType | str
|
The type of calculation that was run. |
required |
stdout |
str | None
|
The program's captured output. |
None
|
directory |
Any
|
The calculation directory holding output files. |
None
|
input_data |
ProgramInput | None
|
The input used for the calculation, for parsers that need it. |
None
|
failed |
bool
|
Recover available data from a failed calculation. |
False
|
options |
Mapping[str, Any] | None
|
Overrides for the codec's declared decode options. |
None
|
version |
str | None
|
The program version, when the output does not print it. |
None
|
Returns:
| Type | Description |
|---|---|
StructuredData
|
The qcdata model matching |
Source code in src/qccodec/registry.py
134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 | |
Codecs¶
qccodec.get_codec(program: str | Inputs) -> Codec
¶
Resolve the codec for a program name or input object.
Resolution order: codecs passed to register, built-ins, then codecs installed
by other packages under the qccodec.codecs entry point group. A FileInput
resolves to the pass-through file codec.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
program |
str | Inputs
|
A program name, or an input whose program should be resolved. |
required |
Raises:
| Type | Description |
|---|---|
CodecNotFoundError
|
No codec is available for the program. |
Source code in src/qccodec/registry.py
96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 | |
qccodec.register(codec: Codec) -> Codec
¶
Make a codec resolvable by its program name for this process.
A registered codec takes precedence over a built-in with the same name, so scripts can both add new programs and override shipped integrations. The codec is returned so this can be used as a decorator-style one-liner.
Source code in src/qccodec/registry.py
47 48 49 50 51 52 53 54 55 | |
qccodec.unregister(program: str) -> None
¶
Remove a codec registered with register; built-ins are unaffected.
Source code in src/qccodec/registry.py
58 59 60 | |
qccodec.supported_programs() -> tuple[str, ...]
¶
Built-in and installed plugin program names plus any registered in this process.
Source code in src/qccodec/registry.py
77 78 79 80 | |
qccodec.Codec(program: str, calctypes: Collection[CalcType | str], *, options: Mapping[str, Any] | None = None, encode: Encoder | None = None, decode: Decoder | None = None, failure: Failure | None = None, propagate_wfn: PropagateWfn | None = None, version_key: VersionKey | None = None, parsers: Iterable[ParserSpec] = (), encode_batch: BatchEncoder | None = None, batch_key: BatchKey | None = None, max_batch: int = 32, cap_threads: CapThreads | None = None, errors: Iterable[ErrorRule] = (), converges: bool | Converges = True)
¶
Program-specific translation between qcdata objects and native inputs/outputs.
A codec encodes a ProgramInput into a SubprocessInput or PythonInput
and decodes the native output back into a qcdata *Data object. File-based
programs register small parsers with @codec.parser(...); Python-native
programs supply a decode function instead.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
program |
str
|
Name matched against |
required |
calctypes |
Collection[CalcType | str]
|
Calculation types this codec can encode. |
required |
options |
Mapping[str, Any] | None
|
Decode options and their defaults, e.g. what to collect. Values
passed to |
None
|
encode |
Encoder | None
|
Translate an input into a native invocation. See |
None
|
decode |
Decoder | None
|
Translate native output into data. See |
None
|
failure |
Failure | None
|
Detect a failure the program reported. See |
None
|
propagate_wfn |
PropagateWfn | None
|
|
None
|
version_key |
VersionKey | None
|
Turns the program's version string into a PEP 440 version
for matching parser |
None
|
encode_batch |
BatchEncoder | None
|
Encodes several inputs as one |
None
|
batch_key |
BatchKey | None
|
Returns a key for an input: inputs with equal keys may share a
batch; |
None
|
max_batch |
int
|
The most inputs one batch may hold. |
32
|
cap_threads |
CapThreads | None
|
|
None
|
errors |
Iterable[ErrorRule]
|
The program's known failures, as |
()
|
converges |
bool | Converges
|
Whether a calculation has convergence settings an accuracy
target could set (an SCF): True, False (a force field, an ML
potential), or a function of the input (xtb: not for GFN-FF). It decides
what becomes of the shared keyword |
True
|
parsers |
Iterable[ParserSpec]
|
Pre-built parser specifications. |
()
|
Raises:
| Type | Description |
|---|---|
RegistryError
|
Only one of |
Source code in src/qccodec/codec.py
230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 | |
encoder(func: F) -> F
¶
Register func(input_data) -> SubprocessInput | PythonInput.
Source code in src/qccodec/codec.py
293 294 295 296 | |
decoder(func: F) -> F
¶
Register func(input_data, native_output) -> Data in place of parsers.
Raises:
| Type | Description |
|---|---|
RegistryError
|
The codec has parsers or options, which only the parser pipeline uses. |
Source code in src/qccodec/codec.py
298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 | |
failure(func: F) -> F
¶
Register func(ctx) returning a message if the program failed, else None.
A message makes decoding recover partial data and then raise
CalculationError with that data attached. A failure with structured facts
returns (message, details) instead: details becomes the error's
qcdata.ErrorInfo.details (for host_memory and device_memory,
required_gib and available_gib, as qcdata's conventions name them).
Source code in src/qccodec/codec.py
316 317 318 319 320 321 322 323 324 325 326 | |
warning(func: F) -> F
¶
Register func(ctx) returning the warnings a run's output gives.
For results a program delivered but the caller should know about, such as an
SCF it accepted unconverged (code loosely_converged). It runs on every
output, failed or not, and returns an empty list when there is nothing to say.
Source code in src/qccodec/codec.py
328 329 330 331 332 333 334 335 336 | |
warnings(input_data: ProgramInput, *, stdout: str | None = None, directory: str | Path | None = None) -> list[ProgramWarning]
¶
The warnings the codec's warning hook finds in a run's output.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
input_data |
ProgramInput
|
The input that produced the output. |
required |
stdout |
str | None
|
The program's captured output. |
None
|
directory |
str | Path | None
|
The calculation directory holding output files. |
None
|
Source code in src/qccodec/codec.py
338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 | |
add_error(pattern: str, kind: str, code: str | None = None) -> None
¶
Classify failures whose message matches pattern (see errors).
Raises:
| Type | Description |
|---|---|
RegistryError
|
|
Source code in src/qccodec/codec.py
364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 | |
classify(message: str) -> tuple[str, str | None]
¶
Return the kind and code of a failure from its message.
Returns:
| Type | Description |
|---|---|
str
|
The kind and code of the first |
str | None
|
|
Source code in src/qccodec/codec.py
380 381 382 383 384 385 386 387 388 389 390 | |
parser(*, target: Target | None = None, calctypes: Collection[CalcType | str] | None = None, file: FileRef = STDOUT, required: bool = True, versions: str | None = None) -> Callable[[F], F]
¶
Register a parser function.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
target |
Target | None
|
Result field to fill, or a tuple for a nested field. Directory parsers may omit it and return a mapping merged into the result. |
None
|
calctypes |
Collection[CalcType | str] | None
|
Calculation types this parser applies to; all when omitted. |
None
|
file |
FileRef
|
|
STDOUT
|
required |
bool
|
If True, a missing file or |
True
|
versions |
str | None
|
Program versions this parser applies to, as a PEP 440
specifier such as |
None
|
Returns:
| Type | Description |
|---|---|
Callable[[F], F]
|
The original function, unchanged, so it can be called and tested directly. |
Source code in src/qccodec/codec.py
392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 | |
encode(input_data: Inputs) -> NativeInput
¶
Translate an input into a native invocation without executing it.
The shared keyword accuracy is checked here for every codec
(accuracy) and left out before the codec's encoder sees the input: the
program never sees it.
Raises:
| Type | Description |
|---|---|
EncoderError
|
The codec has no encoder, the input's program or
calculation type is not supported, the input sets an |
Source code in src/qccodec/codec.py
476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 | |
accuracy(inp: ProgramInput) -> Accuracy | None
¶
Read the input's accuracy target, refusing one the calculation cannot honour.
The shared keyword accuracy is read with qcdata.Accuracy.from_keywords,
as every program reads it; null sets no target. A calculation without
convergence settings (converges false: an ML potential, a GFN-FF or
non-SCC DFTB single point) meets any target as it is, so it accepts one and
records it as met (accuracy_record). One with convergence settings refuses
it, since no codec turns a target into its program's thresholds yet.
Returns:
| Type | Description |
|---|---|
Accuracy | None
|
The target the calculation accepts, or None when it sets none. |
Raises:
| Type | Description |
|---|---|
EncoderError
|
Kind |
Source code in src/qccodec/codec.py
511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 | |
batch_key(input_data: Inputs) -> Hashable | None
¶
Return the key under which an input may share a batch, or None.
None when the codec cannot batch, the input is not a ProgramInput this
codec computes, or the codec computes this input alone (for example a
Hessian, where libraries take one structure at a time), or the input sets an
accuracy the codec refuses, so that its refusal names the input.
Source code in src/qccodec/codec.py
550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 | |
encode_batch(inputs: Sequence[ProgramInput]) -> PythonInput
¶
Encode inputs that share a batch key as one Python invocation.
Its function returns a list of native values, one per input in order;
decode each with decode(input, PythonOutput(value=...)).
Raises:
| Type | Description |
|---|---|
EncoderError
|
The codec cannot batch, the list is empty or longer than
|
Source code in src/qccodec/codec.py
571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 | |
decode(input_data: Inputs, native_output: NativeOutput, options: Mapping[str, Any] | None = None) -> Data
¶
Interpret native output, returning data or raising with partial data.
When the run failed (for example a nonzero exit status), whatever can be
parsed is recovered, and if the codec's failure hook explains the failure
CalculationError carries that explanation and the recovered data.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
input_data |
Inputs
|
The input that produced the output. |
required |
native_output |
NativeOutput
|
What the runner observed. |
required |
options |
Mapping[str, Any] | None
|
Overrides for this codec's declared |
None
|
Raises:
| Type | Description |
|---|---|
CalculationError
|
The program failed and the failure hook (or the
decoder) says why; its kind and code come from the codec's
|
ParserError
|
A required output is missing or malformed in a run that did not fail. |
Source code in src/qccodec/codec.py
601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 | |
parse(calctype: CalcType | str, *, stdout: str | None = None, directory: str | Path | None = None, input_data: ProgramInput | None = None, failed: bool = False, options: Mapping[str, Any] | None = None, version: str | None = None, as_dict: bool = False, check_failure: bool = True, report_failure: bool | None = None) -> StructuredData | dict[str, Any]
¶
Run this codec's parsers over saved artifacts without running the program.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
calctype |
CalcType | str
|
The type of calculation that produced the artifacts. |
required |
stdout |
str | None
|
The program's captured output. |
None
|
directory |
str | Path | None
|
The calculation directory holding output files. |
None
|
input_data |
ProgramInput | None
|
The input used for the calculation, for parsers that need it. |
None
|
failed |
bool
|
Recover what is available from a failed calculation. Missing files and values are tolerated; malformed values still fail. |
False
|
options |
Mapping[str, Any] | None
|
Overrides for this codec's declared |
None
|
version |
str | None
|
The program version, when the output does not print it or should be overridden. Otherwise the version parser supplies it. |
None
|
as_dict |
bool
|
Return the collected values instead of a validated model. |
False
|
check_failure |
bool
|
Run the codec's failure hook first. Nested decodes of partial logs turn this off. |
True
|
report_failure |
bool | None
|
Raise |
None
|
Returns:
| Type | Description |
|---|---|
StructuredData | dict[str, Any]
|
The qcdata model for |
Raises:
| Type | Description |
|---|---|
ParserError
|
A required file is missing or a value is malformed. |
MatchNotFoundError
|
A required parser found no match. |
CalculationError
|
The failure hook explained a failure and
|
Source code in src/qccodec/codec.py
677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 | |
qccodec.Context(codec: Codec, calctype: CalcType, stdout: str | None = None, directory: Path | None = None, input_data: ProgramInput | None = None, failed: bool = False, options: dict[str, Any] = dict(), version: str | None = None)
dataclass
¶
Everything a parser may need beyond the contents of one file.
Attributes:
| Name | Type | Description |
|---|---|---|
codec |
Codec
|
The codec running the decode; used for nested decoding. |
calctype |
CalcType
|
The calculation type being decoded. |
stdout |
str | None
|
Captured program output, if available. |
directory |
Path | None
|
The calculation directory, if available. |
input_data |
ProgramInput | None
|
The input used for the calculation, if available. |
failed |
bool
|
Whether partial data is being recovered from a failed run. |
options |
dict[str, Any]
|
The codec's options merged with those passed for this decode. |
version |
str | None
|
The program version string, once known. |
path(pattern: str) -> Path
¶
Resolve a file name or glob pattern to exactly one path in the directory.
Raises:
| Type | Description |
|---|---|
FileNotFoundError
|
No directory is available or nothing matches. |
ParserError
|
The pattern matches more than one file. |
Source code in src/qccodec/codec.py
118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 | |
read(pattern: str) -> str
¶
Read the text of the single file matching a name or glob pattern.
Source code in src/qccodec/codec.py
135 136 137 | |
contents(spec: ParserSpec) -> Any
¶
Return what a parser receives: stdout, this context, or a file's text.
Raises:
| Type | Description |
|---|---|
FileNotFoundError
|
The parser's input is not available. |
Source code in src/qccodec/codec.py
139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 | |
decode(calctype: CalcType | str, *, stdout: str | None = None, directory: str | Path | None = None) -> StructuredData
¶
Parse another set of artifacts with this codec, e.g. one trajectory step.
The failure hook is not run again: the whole run was already checked before this parser was called, and partial logs such as one optimization step would not pass a whole-run check.
Source code in src/qccodec/codec.py
155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 | |
qccodec.ParserSpec(parser: Callable[..., Any], file: FileRef, calctypes: frozenset[CalcType], required: bool, target: Target | None, versions: SpecifierSet | None = None)
dataclass
¶
A registered parser and the metadata that decides when it runs.
Attributes:
| Name | Type | Description |
|---|---|---|
parser |
Callable[..., Any]
|
The parser function. It receives file contents, or a |
file |
FileRef
|
|
calctypes |
frozenset[CalcType]
|
Calculation types for which this parser runs. |
required |
bool
|
Whether a missing file or value fails decoding. |
target |
Target | None
|
Where the parsed value is stored on the result. A tuple creates
nested fields. |
versions |
SpecifierSet | None
|
Program versions this parser applies to, as a PEP 440
specifier set; |
Native inputs and outputs¶
qccodec.SubprocessInput(command: tuple[str, ...], files: Mapping[str, str | bytes] = dict(), wavefunction_files: tuple[str, ...] = (), environment: Mapping[str, str] = dict(), threads: int | None = None, gpus: int = 0)
dataclass
¶
A command and the files it needs, to run inside a calculation directory.
Attributes:
| Name | Type | Description |
|---|---|---|
command |
tuple[str, ...]
|
The argument vector; the executable is the first element. |
files |
Mapping[str, str | bytes]
|
Files written to the calculation directory before running. |
wavefunction_files |
tuple[str, ...]
|
Relative glob patterns of restart files worth keeping. |
environment |
Mapping[str, str]
|
Environment defaults required by the program. |
threads |
int | None
|
CPU threads the calculation requests (ORCA |
gpus |
int
|
GPUs the calculation uses; a runner gives each calculation its own. |
qccodec.PythonInput(function: Callable[..., Any], args: tuple[Any, ...] = (), kwargs: Mapping[str, Any] = dict(), files: Mapping[str, str | bytes] = dict(), child_callback: str | None = None, children_callback: str | None = None, directory_keyword: str | None = None, device_keyword: str | None = None, loggers: tuple[str, ...] = (), wavefunction_files: tuple[str, ...] = (), environment: Mapping[str, str] = dict(), threads: int | None = None, gpus: int = 0)
dataclass
¶
A Python callable with its arguments, to run inside a calculation directory.
Attributes:
| Name | Type | Description |
|---|---|---|
function |
Callable[..., Any]
|
The callable to invoke. |
args |
tuple[Any, ...]
|
Positional arguments. |
kwargs |
Mapping[str, Any]
|
Keyword arguments. |
files |
Mapping[str, str | bytes]
|
Files written to the calculation directory before running. |
child_callback |
str | None
|
Keyword name into which the runner injects a function that computes child calculations synchronously; only for integrations such as optimizers that drive other programs. |
children_callback |
str | None
|
Keyword name into which the runner injects a function that
computes several independent child calculations at once and returns
their outputs in order ( |
directory_keyword |
str | None
|
Keyword name into which the runner injects the calculation
directory (an absolute |
device_keyword |
str | None
|
Keyword name into which the runner injects the device it
granted a calculation that uses GPUs ( |
loggers |
tuple[str, ...]
|
Python logger names whose output should be captured: the loggers that emit the records, since a logger's own filters do not see its children's. |
wavefunction_files |
tuple[str, ...]
|
Relative glob patterns of restart files worth keeping. |
environment |
Mapping[str, str]
|
Environment defaults required by the library. |
threads |
int | None
|
CPU threads the calculation requests; None: the runner's grant. |
gpus |
int
|
GPUs the calculation uses; a runner gives each calculation its own. |
qccodec.SubprocessOutput(stdout: str = '', directory: Path | None = None, returncode: int | None = None, error: Exception | None = None, traceback: str | None = None)
dataclass
¶
What a subprocess produced; stdout holds merged stdout and stderr.
failed: bool
property
¶
Whether launching or running the process failed.
qccodec.PythonOutput(value: Any = None, stdout: str = '', directory: Path | None = None, error: Exception | None = None, traceback: str | None = None)
dataclass
¶
What a Python callable produced: its return value, merged logs, or an error.
failed: bool
property
¶
Whether invoking the callable raised an exception.
Parsing helpers¶
qccodec.re_search(regex: str, contents: str, flags: int = 0) -> re.Match[str]
¶
Return the first match of regex in contents.
Raises:
| Type | Description |
|---|---|
MatchNotFoundError
|
No match is found. |
Source code in src/qccodec/utils.py
10 11 12 13 14 15 16 17 18 19 | |
qccodec.re_finditer(regex: str, contents: str, flags: int = 0) -> list[re.Match[str]]
¶
Return all matches of regex in contents.
Raises:
| Type | Description |
|---|---|
MatchNotFoundError
|
No match is found. |
Source code in src/qccodec/utils.py
22 23 24 25 26 27 28 29 30 31 | |
Checking keywords¶
qccodec.reject_unknown(program: str, keywords: Iterable[str], known: Collection[str], *, where: str = 'keyword') -> None
¶
Refuse names that are not settings of the program, so typos fail at once.
Every setting given must affect the calculation, and a misspelled one would otherwise be ignored or reach the program as something else.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
program |
str
|
The program, for the message. |
required |
keywords |
Iterable[str]
|
The names given. |
required |
known |
Collection[str]
|
The names the program accepts here. |
required |
where |
str
|
What the names are, for the message ( |
'keyword'
|
Raises:
| Type | Description |
|---|---|
EncoderError
|
Kind |
Source code in src/qccodec/programs/_common.py
64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 | |
Exceptions¶
Exceptions raised by codecs, parsers, and the registry.
BaseError
¶
Base class for qccodec exceptions.
DecoderError
¶
Raised when native output cannot be decoded.
EncoderError(message: str, *, kind: str = 'input', code: str | None = None)
¶
An input the codec refuses before anything runs.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message |
str
|
Why, naming the setting and, for a misspelled key, the closest one. |
required |
kind |
str
|
The |
'input'
|
code |
str | None
|
The shared code refining it, if one applies: |
None
|
Source code in src/qccodec/exceptions.py
45 46 47 48 49 50 51 | |
ParserError(message: str, data: StructuredData | None = None)
¶
Base class for parser failures; data holds any recovered results.
Source code in src/qccodec/exceptions.py
57 58 59 60 | |
MatchNotFoundError(regex: str, contents: str)
¶
Raised when a parser finds no match for its pattern.
Source code in src/qccodec/exceptions.py
66 67 68 69 70 71 72 | |
RegistryError
¶
Raised when a codec or parser registration is invalid.
DataCollectorError
¶
Raised when two parsers fill the same result field.
CodecNotFoundError(message: str, *, kind: str = 'input', code: str | None = None)
¶
No built-in integration is available for this name.
Source code in src/qccodec/exceptions.py
45 46 47 48 49 50 51 | |
CalculationError(message: str, data: StructuredData | None = None, *, kind: str = 'internal', code: str | None = None, details: dict[str, Any] | None = None)
¶
The program reported failure; data holds any recovered scientific results.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message |
str
|
The program's explanation. |
required |
data |
StructuredData | None
|
The results recovered from the failed run. |
None
|
kind |
str
|
The |
'internal'
|
code |
str | None
|
A code refining the kind ( |
None
|
details |
dict[str, Any] | None
|
Structured facts about the failure, as plain JSON
( |
None
|
Source code in src/qccodec/exceptions.py
102 103 104 105 106 107 108 109 110 111 112 113 114 115 | |
DependencyNotFoundError
¶
A codec explicitly reports an unavailable execution dependency.
StoppedError
¶
A program killed because its caller asked its calculation to stop.
Its calculation fails with kind stopped, keeping what the codec recovers from
the program's output so far.
Testing codecs¶
Test helpers for codecs: fixture cases, a case runner, and a codec contract check.
A case is a directory holding one program run and what a codec must make of it::
tests/data/<program>/<case>/
input.json ProgramInput used for the run (program, calctype, structure, ...)
expected.json the qcdata *Data object the codec must produce
stdout captured program output (optional)
<files> output files at their real relative paths, e.g. scr.geom/optim.xyz
case.json optional settings: {"options": {...}, "failed": true,
"raises": "CalculationError", "kind": "convergence",
"code": "scf_not_converged", "details": {...},
"warnings": ["loosely_converged"], "directory": true}
encoded/ optional: command.txt (one argument per line) and the native
input files codec.encode(input) must generate
cases(root) discovers every such directory below root; run_case checks
encoding, the full decode, and each registered parser on its own file against the
matching slice of expected.json; check_codec verifies the structural contract
every codec must satisfy, with or without fixtures.
Typical test module::
import pytest
from qccodec import get_codec
from qccodec.testing import cases, run_case
@pytest.mark.parametrize("case", cases("tests/data"), ids=str)
def test_case(case):
run_case(get_codec(case.input_data.program), case)
Case(path: Path, name: str, input_data: ProgramInput, expected: StructuredData | None, stdout: str | None, directory: Path | None, options: dict[str, Any] = dict(), failed: bool = False, raises: str | None = None, kind: str | None = None, code: str | None = None, details: dict[str, Any] | None = None, warnings: list[str] = list(), encoded: Path | None = None)
dataclass
¶
One fixture directory, loaded.
Attributes:
| Name | Type | Description |
|---|---|---|
path |
Path
|
The case directory; output files live here. |
name |
str
|
|
input_data |
ProgramInput
|
The input that produced the run. |
expected |
StructuredData | None
|
The data the codec must produce, or the partial data attached to
the expected exception. |
stdout |
str | None
|
Captured output, if the case has a |
directory |
Path | None
|
|
options |
dict[str, Any]
|
Decode options passed to the codec. |
failed |
bool
|
Decode in recovery mode. |
raises |
str | None
|
Name of the exception class the decode must raise, if any. |
kind |
str | None
|
The error kind the raised exception must carry ( |
code |
str | None
|
The error code it must carry, if |
details |
dict[str, Any] | None
|
The details a raised |
warnings |
list[str]
|
The codes of the warnings the codec's warning hook must give, in order; none unless given. |
encoded |
Path | None
|
The |
load_case(path: str | Path) -> Case
¶
Load one case directory.
Source code in src/qccodec/testing.py
106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 | |
cases(root: str | Path) -> list[Case]
¶
Discover every case directory below root (any directory holding input.json).
Source code in src/qccodec/testing.py
139 140 141 142 143 | |
assert_data_equal(actual: Any, expected: Any, *, rtol: float = 1e-09, atol: float = 0.0, where: str = 'data') -> None
¶
Compare qcdata objects, arrays, or containers structurally.
Numbers compare within rtol/atol; execution metadata and
qcdata_version are ignored because they vary between runs.
Raises:
| Type | Description |
|---|---|
AssertionError
|
Describing the first difference found. |
Source code in src/qccodec/testing.py
198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 | |
check_encoding(codec: Codec, case: Case, *, rtol: float = 1e-09) -> None
¶
Compare codec.encode(case.input_data) against the case's encoded/ files.
Source code in src/qccodec/testing.py
243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 | |
check_parsers(codec: Codec, case: Case, *, rtol: float = 1e-09, atol: float = 0.0) -> None
¶
Call every applicable parser directly and compare with its expected slice.
Source code in src/qccodec/testing.py
276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 | |
run_case(codec: Codec, case: Case, *, rtol: float = 1e-09, atol: float = 0.0) -> None
¶
Check a codec against one fixture case.
Verifies, in order: the encoded native inputs when encoded/ exists; the
warnings the codec gives, which must have the codes case.json lists (none by
default); the full decode, which must produce expected.json or raise the
exception named in case.json (with its kind, code and details,
when given) with expected.json attached as partial data; and each registered
parser applied directly to its own file.
Raises:
| Type | Description |
|---|---|
AssertionError
|
With a description of the first mismatch. |
Source code in src/qccodec/testing.py
327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 | |
check_codec(codec: Codec, *, inputs: Iterable[ProgramInput] = (), calctypes: Collection[CalcType] | None = None) -> None
¶
Verify the structural contract every codec must satisfy.
Checks that parser targets name real result fields for every calculation type
they apply to, that decoding nothing in recovery mode yields a typed empty result
and in strict mode raises with typed partial data, that option defaults are
well formed, and that encoding each of inputs yields a native invocation whose
files stay inside the calculation directory.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
codec |
Codec
|
The codec to check. |
required |
inputs |
Iterable[ProgramInput]
|
Inputs the codec must be able to encode. |
()
|
calctypes |
Collection[CalcType] | None
|
Calculation types to exercise; defaults to |
None
|
Raises:
| Type | Description |
|---|---|
AssertionError
|
Listing every problem found. |
Source code in src/qccodec/testing.py
418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 | |
check_normal_modes(data: Any, symbols: list[str], *, min_overlap: float = 0.97, rtol: float = 0.01) -> None
¶
Verify normal modes follow qcdata's definition and match the Hessian.
Each mode must have unit length, there must be one per frequency, and, when the data has a Hessian, each mode weighted by the square root of the atomic masses must be (nearly) an eigenvector of the mass-weighted Hessian whose eigenvalue gives the reported frequency. This catches modes in the wrong frame, the wrong atom order, or a mass-weighted convention.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data |
Any
|
A |
required |
symbols |
list[str]
|
The input structure's element symbols. |
required |
min_overlap |
float
|
Smallest acceptable overlap with the Hessian's eigenvector; below 1 for programs that print modes with few digits. |
0.97
|
rtol |
float
|
Relative tolerance between reported and Hessian frequencies. |
0.01
|
Raises:
| Type | Description |
|---|---|
AssertionError
|
Listing every problem found. |
Source code in src/qccodec/testing.py
532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 | |