Inputs

Input structures for specifying quantum chemistry calculations. The most commonly used structure is a ProgramInput which tells a single program how to run a calculation.

A DualProgramInput is used when two programs are used in conjunction for an operation. For example, doing a geometry optimization with geomeTRIC while using a subprogram like TeraChem or Psi4 to compute the gradients.

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 qcio 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 for a calculation. Using qcop you can submit a FileInput a QC program and all output files and stdout produced by that program will be collected and returned in a user-friendly ProgramOutput object. FileInput allows you to continue to use qcio even for calculations that haven't yet been standardized.

qcio.Inputs `module-attribute` ¶

Inputs = Union[FileInput, ProgramInput, DualProgramInput]

qcio.ProgramInput ¶

ProgramInput(**data: Any)

Input for a single quantum chemistry program. This is the most common input type.

Attributes:

Name	Type	Description
`calctype`	`CalcType`	The type of calculation to perform.
`model`	`Model`	The model for the quantum chemistry calculation.
`keywords`	`Dict[str, Any]`	A dict of keywords to be passed to the program excluding model and calctype. Defaults to an empty dict.
`structure`	`Structure`	The structure to be used in the calculation.
`files`	`Files`	Files to be passed to the QC program.
`extras`	`Dict[str, Any]`	Additional information to bundle with the object. Use for schema development and scratch space.

Example

from qcio.models import ProgramInput, Structure

struct = Structure.open("path/to/structure.xyz")

prog_inp = ProgramInput(
    calctype = "energy",
    structure = struct,
    model = {"method": "hf", "basis": "6-31G"},
    keywords = {"maxsteps": "250"},  # Optional
    files = {"file1": b"binary data"}  # Optional
)

Source code in qcio/models/inputs.py

def __init__(self, **data: Any):
    """Backwards compatibility for 'molecule' attribute."""

    # TODO: Remove in future versions.
    if "molecule" in data:
        warnings.warn(
            "Use of 'molecule' attribute is deprecated. Use 'structure' instead.",
            FutureWarning,
            stacklevel=2,
        )
        data["structure"] = data.pop("molecule")
    super().__init__(**data)

add_file ¶

add_file(
    filepath: Union[Path, str],
    relative_dir: Optional[Path] = None,
) -> None

Add a file to the object. The file will be added at to the files attribute with the filename as the key and the file data as the value.

Parameters:

Name	Type	Description	Default
`filepath`	`Union[Path, str]`	The path to the file.	required
`relative_dir`	`Optional[Path]`	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 qcio/models/base_models.py

def add_file(
    self, filepath: Union[Path, str], relative_dir: Optional[Path] = None
) -> None:
    """Add a file to the object. The file will be added at to the `files` attribute
        with the filename as the key and the file data as the value.

    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: Union[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: Optional[List[str]] = 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`	`Optional[List[str]]`	A list of filenames to exclude from the directory.	`None`

Source code in qcio/models/base_models.py

def add_files(
    self,
    directory: StrOrPath,
    recursive: bool = False,
    exclude: Optional[List[str]] = 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

Source code in qcio/models/base_models.py

def save_files(self, directory: StrOrPath = Path(".")) -> None:
    """Write all files to the specified 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)

qcio.DualProgramInput ¶

DualProgramInput(**data: Any)

Input for a two program calculation.

Attributes:

Name	Type	Description
`calctype`	`CalcType`	The type of calculation to perform.
`model`	`Model`	The model for the quantum chemistry calculation.
`keywords`	`Dict[str, Any]`	A dict of keywords to be passed to the program excluding model and calctype. Defaults to an empty dict.
`structure`	`Structure`	The structure to be used in the calculation.
`files`	`Files`	Files to be passed to the QC program.
`subprogram`	`Files`	The name of the subprogram to use.
`subprogram_args`	`ProgramArgs`	The ProgramArgs for the subprogram.
`extras`	`Dict[str, Any]`	Additional information to bundle with the object. Use for schema development and scratch space.

Example

from qcio.models import DualProgramInput, Structure

struct = Structure.open("path/to/structure.xyz")

prog_inp = DualProgramInput(
    calctype = "optimization",
    structure = struct,
    keywords = {"maxiter": "250"},  # Optional
    subprogram = "orca",
    subprogram_args = ProgramArgs(
        model = {"method": "wb97x-d3", "basis": "def2-SVP"},
        keywords = {"convthre": "1e-6"},  # Optional
    )
)

Source code in qcio/models/inputs.py

def __init__(self, **data: Any):
    """Backwards compatibility for 'molecule' attribute."""

    # TODO: Remove in future versions.
    if "molecule" in data:
        warnings.warn(
            "Use of 'molecule' attribute is deprecated. Use 'structure' instead.",
            FutureWarning,
            stacklevel=2,
        )
        data["structure"] = data.pop("molecule")
    super().__init__(**data)

qcio.FileInput ¶

File and command line argument inputs for a calculation.

Attributes:

Name	Type	Description
`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: Union[Path, str],
    relative_dir: Optional[Path] = None,
) -> None

Add a file to the object. The file will be added at to the files attribute with the filename as the key and the file data as the value.

Parameters:

Name	Type	Description	Default
`filepath`	`Union[Path, str]`	The path to the file.	required
`relative_dir`	`Optional[Path]`	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 qcio/models/base_models.py

def add_file(
    self, filepath: Union[Path, str], relative_dir: Optional[Path] = None
) -> None:
    """Add a file to the object. The file will be added at to the `files` attribute
        with the filename as the key and the file data as the value.

    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: Union[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: Optional[List[str]] = 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`	`Optional[List[str]]`	A list of filenames to exclude from the directory.	`None`

Source code in qcio/models/base_models.py

def add_files(
    self,
    directory: StrOrPath,
    recursive: bool = False,
    exclude: Optional[List[str]] = 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

Source code in qcio/models/base_models.py

def save_files(self, directory: StrOrPath = Path(".")) -> None:
    """Write all files to the specified 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: Union[Path, str], **kwargs
) -> Self

Create a new FileInput and collect all files in the directory.

Source code in qcio/models/inputs.py

@classmethod
def from_directory(cls, directory: Union[Path, str], **kwargs) -> Self:
    """Create a new FileInput and collect all files in the directory."""
    obj = cls(**kwargs)
    directory = Path(directory)
    obj.add_files(directory)
    return obj

qcio.ProgramArgs ¶

Generic arguments for a program without a calctype or structure specification.

This class is used by DualProgramInput or multi-step calculations to specify subprogram_args or a basic program arguments multistep algorithm in BigChem. It is not intended to be used directly for single-step calculations since it lacks a calctype and structure.

Attributes:

Name	Type	Description
`model`	`Model`	The model for the quantum chemistry calculation.
`keywords`	`Dict[str, Any]`	A dict of keywords to be passed to the program excluding model and calctype. Defaults to an empty dict.
`files`	`Files`	Files to be passed to the QC program.
`extras`	`Dict[str, Any]`	Additional information to bundle with the object. Use for schema development and scratch space.

add_file ¶

add_file(
    filepath: Union[Path, str],
    relative_dir: Optional[Path] = None,
) -> None

Add a file to the object. The file will be added at to the files attribute with the filename as the key and the file data as the value.

Parameters:

Name	Type	Description	Default
`filepath`	`Union[Path, str]`	The path to the file.	required
`relative_dir`	`Optional[Path]`	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 qcio/models/base_models.py

def add_file(
    self, filepath: Union[Path, str], relative_dir: Optional[Path] = None
) -> None:
    """Add a file to the object. The file will be added at to the `files` attribute
        with the filename as the key and the file data as the value.

    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: Union[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: Optional[List[str]] = 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`	`Optional[List[str]]`	A list of filenames to exclude from the directory.	`None`

Source code in qcio/models/base_models.py

def add_files(
    self,
    directory: StrOrPath,
    recursive: bool = False,
    exclude: Optional[List[str]] = 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

Source code in qcio/models/base_models.py

def save_files(self, directory: StrOrPath = Path(".")) -> None:
    """Write all files to the specified 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)

Inputs

qcio.Inputs module-attribute ¶

qcio.ProgramInput ¶

add_file ¶

add_files ¶

save_files ¶

qcio.DualProgramInput ¶

qcio.FileInput ¶

add_file ¶

add_files ¶

save_files ¶

from_directory classmethod ¶

qcio.ProgramArgs ¶

add_file ¶

add_files ¶

save_files ¶

qcio.Inputs `module-attribute` ¶

from_directory `classmethod` ¶