Skip to content

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.Inputs module-attribute

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 (path_optimization).

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 "initial_chain".

given SinglePointData | None

Results already known at structure, for the program to start from: an optimizer or IRC takes a given Hessian as its starting Hessian; an SCF starts from a given wavefunction. Starting points, never results: a program does not report a given value as its own. A record of what is known, not a request: a program uses the fields it can, records each one used in its resolved settings ("given"), and leaves the rest alone, so given=frame.results works as it stands. It refuses the input (not_applicable) when it can use none of the fields, or when a field it would use does not fit (another basis). provenance names only the producing program and version; checking the model is the caller's, which knows the producing input. Part of the input, so part of a stored calculation's key.

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
def get_subprogram(self, calctype: CalcType | str) -> "ProgramSpec":
    """Return an immediate child by CalcType or string value.

    Raises ValueError if no matching immediate child exists.
    """
    for child in self.subprograms:
        if child.calctype == calctype:
            return child
    raise ValueError(
        f"No immediate subprogram with calculation type {calctype!r} "
        f"for program '{self.program}'."
    )

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
def add_file(self, 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`.

    Args:
        filepath: The path to the file.
        relative_dir: The directory to make the file relative to. Helpful when
            adding files from a subdirectory.

    Example:
        ```python
            my_obj.add_file("path/to/file.txt")
            print(my_obj.files)
            # Output: {"file.txt": "file data"}
        ```
    """
    filepath = Path(filepath)
    raw_bytes = filepath.read_bytes()
    try:
        data: str | bytes = raw_bytes.decode("utf-8")  # str
    except UnicodeDecodeError:
        data = raw_bytes  # bytes

    # Set filename relative to relative_dir
    if relative_dir:
        filename = str(filepath.relative_to(relative_dir))
    else:
        filename = filepath.name

    self.files[filename] = data
    # Add files to __pydantic_fields_set__ to ensure they are included in .save()
    self.__pydantic_fields_set__.add("files")

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
def add_files(
    self,
    directory: StrOrPath,
    recursive: bool = False,
    exclude: list[str] | None = None,
) -> None:
    """Add all files in a directory to the object.

    Args:
        directory: The directory to add files from.
        recursive: Whether to recursively add files from subdirectories.
        exclude: A list of filenames to exclude from the directory.
    """
    directory = Path(directory)
    if exclude is None:
        exclude = []
    if recursive:
        files = directory.rglob("*")
    else:
        files = directory.glob("*")
    for filepath in files:
        if filepath.is_file() and filepath.name not in exclude:
            self.add_file(filepath, directory)

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
def save_files(self, 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.

    Args:
        directory: The directory to write the files to. Created if it does not
            exist (its parent must already exist). Defaults to the current
            working directory.
    """
    directory = Path(directory)
    directory.mkdir(exist_ok=True)
    for filename, data in self.files.items():
        mode = "w" if isinstance(data, str) else "wb"
        filepath = directory / filename
        # In case filename is a relative path, create the parent directories
        filepath.parent.mkdir(exist_ok=True, parents=True)
        filepath.open(mode).write(data)

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 Accuracy) is stored as its JSON form without nulls, so the input and its calculation key are the same before and after a save.

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
def get_subprogram(self, calctype: CalcType | str) -> "ProgramSpec":
    """Return an immediate child by CalcType or string value.

    Raises ValueError if no matching immediate child exists.
    """
    for child in self.subprograms:
        if child.calctype == calctype:
            return child
    raise ValueError(
        f"No immediate subprogram with calculation type {calctype!r} "
        f"for program '{self.program}'."
    )

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
def add_file(self, 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`.

    Args:
        filepath: The path to the file.
        relative_dir: The directory to make the file relative to. Helpful when
            adding files from a subdirectory.

    Example:
        ```python
            my_obj.add_file("path/to/file.txt")
            print(my_obj.files)
            # Output: {"file.txt": "file data"}
        ```
    """
    filepath = Path(filepath)
    raw_bytes = filepath.read_bytes()
    try:
        data: str | bytes = raw_bytes.decode("utf-8")  # str
    except UnicodeDecodeError:
        data = raw_bytes  # bytes

    # Set filename relative to relative_dir
    if relative_dir:
        filename = str(filepath.relative_to(relative_dir))
    else:
        filename = filepath.name

    self.files[filename] = data
    # Add files to __pydantic_fields_set__ to ensure they are included in .save()
    self.__pydantic_fields_set__.add("files")

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
def add_files(
    self,
    directory: StrOrPath,
    recursive: bool = False,
    exclude: list[str] | None = None,
) -> None:
    """Add all files in a directory to the object.

    Args:
        directory: The directory to add files from.
        recursive: Whether to recursively add files from subdirectories.
        exclude: A list of filenames to exclude from the directory.
    """
    directory = Path(directory)
    if exclude is None:
        exclude = []
    if recursive:
        files = directory.rglob("*")
    else:
        files = directory.glob("*")
    for filepath in files:
        if filepath.is_file() and filepath.name not in exclude:
            self.add_file(filepath, directory)

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
def save_files(self, 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.

    Args:
        directory: The directory to write the files to. Created if it does not
            exist (its parent must already exist). Defaults to the current
            working directory.
    """
    directory = Path(directory)
    directory.mkdir(exist_ok=True)
    for filename, data in self.files.items():
        mode = "w" if isinstance(data, str) else "wb"
        filepath = directory / filename
        # In case filename is a relative path, create the parent directories
        filepath.parent.mkdir(exist_ok=True, parents=True)
        filepath.open(mode).write(data)

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
def add_file(self, 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`.

    Args:
        filepath: The path to the file.
        relative_dir: The directory to make the file relative to. Helpful when
            adding files from a subdirectory.

    Example:
        ```python
            my_obj.add_file("path/to/file.txt")
            print(my_obj.files)
            # Output: {"file.txt": "file data"}
        ```
    """
    filepath = Path(filepath)
    raw_bytes = filepath.read_bytes()
    try:
        data: str | bytes = raw_bytes.decode("utf-8")  # str
    except UnicodeDecodeError:
        data = raw_bytes  # bytes

    # Set filename relative to relative_dir
    if relative_dir:
        filename = str(filepath.relative_to(relative_dir))
    else:
        filename = filepath.name

    self.files[filename] = data
    # Add files to __pydantic_fields_set__ to ensure they are included in .save()
    self.__pydantic_fields_set__.add("files")

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
def add_files(
    self,
    directory: StrOrPath,
    recursive: bool = False,
    exclude: list[str] | None = None,
) -> None:
    """Add all files in a directory to the object.

    Args:
        directory: The directory to add files from.
        recursive: Whether to recursively add files from subdirectories.
        exclude: A list of filenames to exclude from the directory.
    """
    directory = Path(directory)
    if exclude is None:
        exclude = []
    if recursive:
        files = directory.rglob("*")
    else:
        files = directory.glob("*")
    for filepath in files:
        if filepath.is_file() and filepath.name not in exclude:
            self.add_file(filepath, directory)

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
def save_files(self, 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.

    Args:
        directory: The directory to write the files to. Created if it does not
            exist (its parent must already exist). Defaults to the current
            working directory.
    """
    directory = Path(directory)
    directory.mkdir(exist_ok=True)
    for filename, data in self.files.items():
        mode = "w" if isinstance(data, str) else "wb"
        filepath = directory / filename
        # In case filename is a relative path, create the parent directories
        filepath.parent.mkdir(exist_ok=True, parents=True)
        filepath.open(mode).write(data)

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
@classmethod
def from_directory(cls, directory: Path | str, **kwargs: Any) -> Self:
    """Collect directory files, passing required `program` and other fields as kwargs."""
    obj = cls(**kwargs)
    directory = Path(directory)
    obj.add_files(directory)
    return obj

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.