Inputs
Data structures for specifying quantum chemistry calculations. The most commonly used structure is a ProgramInput which defines a single calculation.
The hierarchy is Files → FileInput → ProgramSpec → ProgramInput. Every input requires program, the requested executor; ProgramOutput.results.provenance.program records the program that actually produced the result.
ProgramSpec describes a calculation without structures. It has its own program, calctype, optional model, keywords, files, cmdline_args, extras, and recursive subprograms. Model remains a distinct scientific concept with method and basis. A program without a meaningful model, such as an optimizer, can leave model=None.
from qcdata import CalcType, ProgramInput, ProgramSpec, Structure
input_data = ProgramInput(
program="geometric",
calctype="optimization",
structure=Structure.open("structure.xyz"),
keywords={"maxiter": 250},
subprograms=[
ProgramSpec(
program="terachem",
calctype="gradient",
model={"method": "wb97x-d3", "basis": "def2-svp"},
keywords={"convthre": 1e-6},
),
],
)
gradient_spec = input_data.get_subprogram(CalcType.gradient)
Children can contain further subprograms to arbitrary depth. Each immediate child must have a unique CalcType among its siblings. get_subprogram(calctype) accepts a CalcType or its string value (for example, CalcType.gradient or "gradient"), searches immediate children only, and raises ValueError if missing.
Inputs is FileInput | ProgramInput. Use ProgramInput directly for structured inputs. A ProgramSpec alone is not a top-level input because it lacks structures. Use structure for the constructor argument and attribute; the former molecule API has been removed.
This replaces ProgramArgs, ProgramArgsSub, and DualProgramInput without compatibility aliases. Migrate subprogram and subprogram_args to a subprograms list with an explicit program and calctype on each child. Existing serialized inputs also need these fields. QCSchema AtomicInput conversion requires a non-None model and raises ValueError otherwise.
ProgramInput.structure is the primary/start/reference structure for the calculation. Calculations that require additional complete structures can provide them by role name with ProgramInput.structures, for example structures={"environment": mm_region}. A role may also hold an ordered list of structures. Calculation-specific tools should validate which structure names are required.
A path optimization (calctype="path_optimization": NEB, string, growing string) is about a chain rather than one structure. Its structures, endpoints included and in order, go in structures["initial_chain"], and structure is left out:
ProgramInput(
program="...",
calctype="path_optimization",
structures={"initial_chain": [reactant, *images, product]}, # or [reactant, product]
)
Validation enforces this by calculation type: a path optimization needs a chain of at least two structures with the same atoms and no structure; every other calculation type requires structure. Code that needs one structure calls inp.require_structure(), which returns a Structure (or raises for a chain input) so type checkers know it is not None; inp.initial_chain returns the chain. To restart from a previous path, pass structures={"initial_chain": output.results.final_path.structures}.
FileInput.from_directory("inputs", program="psi4") collects native input files with the required executor identity.
A FileInput is an escape hatch that allows you to run any calculation in any QC program (or any program for that matter), even if it isn't a supported CalcType in qcdata yet. You can use a FileInput to store the native input files (text and binary) for a QC program along with the relevant command line args. Using qcop you can submit a FileInput to a QC program and all output files and logs produced by that program will be collected and returned in a user-friendly ProgramOutput object. FileInput allows you to continue to use qcdata even for calculations that haven't yet been standardized.
qcdata.ProgramInput
¶
A program specification bound to structures.
Most calculations are about one structure, structure. A path optimization is
about a chain: its structures, endpoints included and in order, go in
structures["initial_chain"] and structure is left out. Validation enforces
this by calculation type, so structure is always set for every other one; use
require_structure() where a type checker needs to know that.
Make a variant by validating changed values,
ProgramInput.model_validate(inp.model_dump() | {"calctype": "hessian"}), or at a
new geometry with from_spec. Pydantic's model_copy(update=...) does not
validate: it would leave calctype a plain string.
Attributes:
| Name | Type | Description |
|---|---|---|
structure |
Structure | None
|
The primary/start/reference structure; None only for chain
calculation types ( |
structures |
dict[str, Structure | list[Structure]]
|
Additional complete structures identified by role, such as a
QM/MM environment, or a list of structures for a role that holds several
in order, such as |
given |
SinglePointData | None
|
Results already known at |
Example
from qcdata import ProgramInput, ProgramSpec, Structure
prog_input = ProgramInput(
program="geometric",
calctype="optimization",
structure=Structure.open("structure.xyz"),
keywords={"maxiter": 250},
subprograms=[
ProgramSpec(
program="terachem",
calctype="gradient",
model={"method": "wb97x-d3", "basis": "def2-svp"},
),
],
)
get_subprogram
¶
get_subprogram(calctype: CalcType | str) -> ProgramSpec
Return an immediate child by CalcType or string value.
Raises ValueError if no matching immediate child exists.
Source code in src/qcdata/models/inputs.py
128 129 130 131 132 133 134 135 136 137 138 139 | |
add_file
¶
add_file(
filepath: Path | str, relative_dir: Path | None = None
) -> None
Add a file to the object.
The file is added to the files attribute with the filename as the key and
the file data as the value. UTF-8 decodable files are stored as str; all
other files are stored as bytes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
filepath
|
Path | str
|
The path to the file. |
required |
relative_dir
|
Path | None
|
The directory to make the file relative to. Helpful when adding files from a subdirectory. |
None
|
Example
my_obj.add_file("path/to/file.txt")
print(my_obj.files)
# Output: {"file.txt": "file data"}
Source code in src/qcdata/models/base_models.py
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 | |
add_files
¶
add_files(
directory: StrOrPath,
recursive: bool = False,
exclude: list[str] | None = None,
) -> None
Add all files in a directory to the object.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
directory
|
StrOrPath
|
The directory to add files from. |
required |
recursive
|
bool
|
Whether to recursively add files from subdirectories. |
False
|
exclude
|
list[str] | None
|
A list of filenames to exclude from the directory. |
None
|
Source code in src/qcdata/models/base_models.py
494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 | |
save_files
¶
save_files(directory: StrOrPath = Path('.')) -> None
Write all files to the specified directory.
Text data is written in text mode and binary data in binary mode. Parent directories are created for filenames that contain relative paths.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
directory
|
StrOrPath
|
The directory to write the files to. Created if it does not exist (its parent must already exist). Defaults to the current working directory. |
Path('.')
|
Source code in src/qcdata/models/base_models.py
518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 | |
qcdata.ProgramSpec
¶
A recursive program specification, independent of structures.
Each child describes its own calculation. Siblings must have distinct calculation types; the same calculation type may appear at different levels of the tree.
Attributes:
| Name | Type | Description |
|---|---|---|
program |
str
|
The requested executor (distinct from result data provenance). |
calctype |
CalcType
|
The type of calculation to perform. |
model |
Model | None
|
The scientific model, or None for programs without one. |
keywords |
FreeDict
|
Program keywords, excluding model and calculation type. Plain
JSON: a pydantic model given anywhere in them (an |
subprograms |
list[ProgramSpec]
|
Child specifications, with one child per calculation type. |
files |
dict[str, str | bytes]
|
Native input files for this program. |
cmdline_args |
list[str]
|
Command line arguments for this program. |
extras |
FreeDict
|
Additional information to bundle with this specification. |
get_subprogram
¶
get_subprogram(calctype: CalcType | str) -> ProgramSpec
Return an immediate child by CalcType or string value.
Raises ValueError if no matching immediate child exists.
Source code in src/qcdata/models/inputs.py
128 129 130 131 132 133 134 135 136 137 138 139 | |
add_file
¶
add_file(
filepath: Path | str, relative_dir: Path | None = None
) -> None
Add a file to the object.
The file is added to the files attribute with the filename as the key and
the file data as the value. UTF-8 decodable files are stored as str; all
other files are stored as bytes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
filepath
|
Path | str
|
The path to the file. |
required |
relative_dir
|
Path | None
|
The directory to make the file relative to. Helpful when adding files from a subdirectory. |
None
|
Example
my_obj.add_file("path/to/file.txt")
print(my_obj.files)
# Output: {"file.txt": "file data"}
Source code in src/qcdata/models/base_models.py
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 | |
add_files
¶
add_files(
directory: StrOrPath,
recursive: bool = False,
exclude: list[str] | None = None,
) -> None
Add all files in a directory to the object.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
directory
|
StrOrPath
|
The directory to add files from. |
required |
recursive
|
bool
|
Whether to recursively add files from subdirectories. |
False
|
exclude
|
list[str] | None
|
A list of filenames to exclude from the directory. |
None
|
Source code in src/qcdata/models/base_models.py
494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 | |
save_files
¶
save_files(directory: StrOrPath = Path('.')) -> None
Write all files to the specified directory.
Text data is written in text mode and binary data in binary mode. Parent directories are created for filenames that contain relative paths.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
directory
|
StrOrPath
|
The directory to write the files to. Created if it does not exist (its parent must already exist). Defaults to the current working directory. |
Path('.')
|
Source code in src/qcdata/models/base_models.py
518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 | |
qcdata.FileInput
¶
File and command line argument inputs for a calculation.
Attributes:
| Name | Type | Description |
|---|---|---|
program |
str
|
The requested executor for the calculation. |
files |
Files
|
A dict mapping filename to str or bytes data. |
cmdline_args |
list[str]
|
A list of command line arguments to be passed to the program. |
extras |
Dict[str, Any]
|
Additional information to bundle with the object. Use for schema development and scratch space. |
add_file
¶
add_file(
filepath: Path | str, relative_dir: Path | None = None
) -> None
Add a file to the object.
The file is added to the files attribute with the filename as the key and
the file data as the value. UTF-8 decodable files are stored as str; all
other files are stored as bytes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
filepath
|
Path | str
|
The path to the file. |
required |
relative_dir
|
Path | None
|
The directory to make the file relative to. Helpful when adding files from a subdirectory. |
None
|
Example
my_obj.add_file("path/to/file.txt")
print(my_obj.files)
# Output: {"file.txt": "file data"}
Source code in src/qcdata/models/base_models.py
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 | |
add_files
¶
add_files(
directory: StrOrPath,
recursive: bool = False,
exclude: list[str] | None = None,
) -> None
Add all files in a directory to the object.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
directory
|
StrOrPath
|
The directory to add files from. |
required |
recursive
|
bool
|
Whether to recursively add files from subdirectories. |
False
|
exclude
|
list[str] | None
|
A list of filenames to exclude from the directory. |
None
|
Source code in src/qcdata/models/base_models.py
494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 | |
save_files
¶
save_files(directory: StrOrPath = Path('.')) -> None
Write all files to the specified directory.
Text data is written in text mode and binary data in binary mode. Parent directories are created for filenames that contain relative paths.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
directory
|
StrOrPath
|
The directory to write the files to. Created if it does not exist (its parent must already exist). Defaults to the current working directory. |
Path('.')
|
Source code in src/qcdata/models/base_models.py
518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 | |
from_directory
classmethod
¶
from_directory(
directory: Path | str, **kwargs: Any
) -> Self
Collect directory files, passing required program and other fields as kwargs.
Source code in src/qcdata/models/inputs.py
46 47 48 49 50 51 52 | |
Binding a specification to structures¶
input_data = ProgramInput.from_spec(
spec, structure, structures={"reference": reference_structure}
)
This validates a new input while preserving all specification fields and recursive children. The original specification is unchanged. Additional structures are optional and are supplied explicitly when binding.
An input at a new geometry¶
moved = ProgramInput.from_spec(inp, inp.structure.with_geometry(positions))
Structure.with_geometry validates the new positions (bohr) against the atoms and keeps
the charge, multiplicity, connectivity and identifiers; from_spec keeps the program,
model, keywords, subprograms and files. given is left out, because its results belong to
the old geometry; pass structures=inp.structures to keep other roles. Avoid
model_copy(update=...), which skips validation.
A variant of an input¶
To change anything else (another calctype at the same geometry, other keywords), dump the input, change the values and validate a new one:
hessian_inp = ProgramInput.model_validate(inp.model_dump() | {"calctype": "hessian"})
model_validate checks and converts the new values as for any new input: "hessian"
becomes CalcType.hessian, and a value that does not fit is refused. The variant equals
an input built directly with those values and has the same calculation key.
Pydantic's model_copy(update=...) does not validate, as pydantic documents: the copy
holds whatever it was given, so calctype stays the plain string "hessian" (code that
reads inp.calctype.value fails on it) and nothing checks that the new values fit the
rest of the input. Don't use it to make inputs.