qrunch.chemistry.molecule.cube_file_generator

Module for generating cube files.

Functions

`cube_file_generator_creator`()	Create a cube file generator.
`generate_density_cube_file`(...[, nx, ny, ...])	Generate a density cube file.
`generate_molecular_electrostatic_potential_cube_file`(...)	Generate a molecular electrostatic potential (MEP) cube file.
`generate_orbital_cube_file`(...[, nx, ny, nz])	Generate an orbital cube file.
`to_density_component_enum`(value)	Coerce literal to DensityComponent.
`to_overwriting_policy_enum`(value)	Coerce literal to CubeFileOverwritingPolicy.

Classes

`CubeFileOptions`	Options controlling cube file generation.
`CubeFileOverwritingPolicy`	Enum defining how to handle existing cube files.
`CubeGeneratorCreator`	Builder for creating a cube file generator.
`CubeProperty`	The Cube properties that can be produced.
`CubePropertyCreator`	Cube property generator.
`DensityComponent`	Represent density components.
`ProjectiveEmbeddingCubeGenerator`	Generate cube files for embedding and environment densities.
`ProjectiveEmbeddingCubeGeneratorCreator`	Builder for creating a projective embedding cube file generator.

class CubeFileOptions

Bases: DataclassPublicAPI

Options controlling cube file generation.

All fields are immutable (frozen=True) so an instance can be safely reused.

Parameters:

nx – Number of grid point divisions in x direction. Note this is function of the molecule’s size; a larger molecule will have a coarser representation than a smaller one for the same value. Conflicts to keyword resolution. default=80
ny – Number of grid point divisions in y direction.
nz – Number of grid point divisions in z direction.
resolution – Resolution of the mesh grid in the cube box. If resolution is given in the input, the input nx/ny/nz have no effects. The value of nx/ny/nz will be determined by the resolution and the cube box size. Default is None which means nx/ny/nz are used to determine the grid size.

__init__(*, nx: int = 80, ny: int = 80, nz: int = 80, resolution: float | None = None) → None

Parameters:

nx (int)
ny (int)
nz (int)
resolution (float | None)

Return type:

None

nx: int = 80

ny: int = 80

nz: int = 80

resolution: float | None = None

class CubeFileOverwritingPolicy

Bases: Enum

Enum defining how to handle existing cube files.

ERROR = 'error'

IGNORE = 'ignore'

OVERWRITE = 'overwrite'

RENAME = 'rename'

class CubeGeneratorCreator

Bases: object

Builder for creating a cube file generator.

static projective_embedding() → ProjectiveEmbeddingCubeGeneratorCreator

Narrow the cube file generator to a projective embedding cube file generator.

Return type:: ProjectiveEmbeddingCubeGeneratorCreator

class CubeProperty

Bases: Enum

The Cube properties that can be produced.

DENSITY = 'Density'

MEP = 'Molecular Electrostatic Potential'

class CubePropertyCreator

Bases: Generic[T]

Cube property generator.

__init__(parent: T, field_name: str) → None

Initialize a Cube property creator.

Parameters:

parent (T) – Parent object to which the Cube property will be assigned.
field_name (str) – Name of the field in the parent object where the Cube property will be assigned.

Return type:

None

density() → T

Choose the electronic density as the property to generate cube file for.

Return type:: T

molecular_electrostatic_potential() → T

Choose the molecular electrostatic potential as the property to generate cube file for.

Return type:: T

class DensityComponent

Bases: Enum

Represent density components.

Enum containing the three possible density components.

ALPHA = 'alpha'

BETA = 'beta'

TOTAL = 'total'

class ProjectiveEmbeddingCubeGenerator

Bases: object

Generate cube files for embedding and environment densities.

__init__(base_file_path: Path, embedding_components: Sequence[DensityComponent] | None = None, environment_components: Sequence[DensityComponent] | None = None, overwriting_policy: CubeFileOverwritingPolicy = CubeFileOverwritingPolicy.RENAME, options: CubeFileOptions | None = None, cube_property: CubeProperty = CubeProperty.DENSITY) → None

Initialize the cube generator.

Parameters:

base_file_path (Path) – Base path or prefix for output cube files.
embedding_components (Sequence[DensityComponent] | None) – Density components to generate for the embedded system.
environment_components (Sequence[DensityComponent] | None) – Density components to generate for the environment.
overwriting_policy (CubeFileOverwritingPolicy) – Policy for handling existing files: - overwrite: overwrite existing files, - error: raise an error if file exists, - rename: append suffix to avoid collisions.
options (CubeFileOptions | None) – Options for the Cube file generation.
cube_property (CubeProperty) – The cube property to generate cube file for.

Return type:

None

embedding_components: list[DensityComponent]

environment_components: list[DensityComponent]

overwriting_policy: CubeFileOverwritingPolicy

run(embedded_density_operator: RestrictedDensityOperator | UnrestrictedDensityOperator, environment_density_operator: RestrictedDensityOperator | UnrestrictedDensityOperator, molecular_configuration: MolecularConfiguration, post_fix: str | None = None) → None

Generate cube files for selected density components.

Parameters:

embedded_density_operator (RestrictedDensityOperator | UnrestrictedDensityOperator) – Density operator for the embedded system.
environment_density_operator (RestrictedDensityOperator | UnrestrictedDensityOperator) – Density operator for the environment.
molecular_configuration (MolecularConfiguration) – Configuration holding the molecule and orbitals.
post_fix (str | None) – Optional string to append to the base file name before the suffix.

Return type:

None

class ProjectiveEmbeddingCubeGeneratorCreator

Bases: object

Builder for creating a projective embedding cube file generator.

__init__() → None

Initialize the ProjectiveEmbeddingCubeGeneratorCreator.

Return type:: None

choose_property() → CubePropertyCreator[Self]

Choose the cube property to generate cube file for.

Return type:: CubePropertyCreator[Self]

create() → ProjectiveEmbeddingCubeGenerator

Create an instance of ProjectiveEmbeddingCubeGenerator.

Return type:: ProjectiveEmbeddingCubeGenerator

with_base_file_path(path: Path) → Self

Specify the base file path for generated cube files.

Parameters:: path (Path) – Base path or prefix for output cube files.
Return type:: Self

with_embedding_components(components: Sequence[Literal['alpha', 'beta', 'total']]) → Self

Specify which density components to generate for the embedded system.

Parameters:: components (Sequence[Literal['alpha', 'beta', 'total']]) – Density components to generate for the embedded system.
Return type:: Self

with_environment_components(components: Sequence[Literal['alpha', 'beta', 'total']]) → Self

Specify which density components to generate for the environment.

Parameters:: components (Sequence[Literal['alpha', 'beta', 'total']]) – Density components to generate for the environment.
Return type:: Self

with_options(options: CubeFileOptions) → Self

Set options for the Cube file generation.

Parameters:: options (CubeFileOptions) – Options for the Cube file generation.
Return type:: Self

with_overwriting_policy(policy: Literal['overwrite', 'error', 'rename', 'ignore']) → Self

Specify the policy for handling existing files.

Parameters:: policy (Literal['overwrite', 'error', 'rename', 'ignore']) – Policy for handling existing files: - overwrite: overwrite existing files, - error: raise an error if file exists, - rename: append suffix to avoid collisions.
Return type:: Self

cube_file_generator_creator() → CubeGeneratorCreator

Create a cube file generator.

This is the intended starting point for creating any type of cube file generator. See https://qrunch.docs.kvantify.net/docs/explanations/builder_pattern.html for more information on using the builder pattern.

Return type:: CubeGeneratorCreator

generate_density_cube_file(molecular_configuration: MolecularConfiguration, density_operator: RestrictedDensityOperator | UnrestrictedDensityOperator, file_path: Path, component: DensityComponent, nx: int = 80, ny: int = 80, nz: int = 80, resolution: float | None = None) → None

Generate a density cube file.

Parameters:

molecular_configuration (MolecularConfiguration) – Configuration holding the PySCF molecule and spatial-orbital count.
density_operator (RestrictedDensityOperator | UnrestrictedDensityOperator) – Restricted or unrestricted density operator.
file_path (Path) – Path where the cube file will be written.
component (DensityComponent) – Which density component to generate (alpha, beta, or total).
nx (int) – Number of grid point divisions in x direction. Note this is function of the molecule’s size; a larger molecule will have a coarser representation than a smaller one for the same value. Conflicts to keyword resolution. default=80
ny (int) – Number of grid point divisions in y direction.
nz (int) – Number of grid point divisions in z direction.
resolution (float | None) – Resolution of the mesh grid in the cube box. If resolution is given in the input, the input nx/ny/nz have no effects. The value of nx/ny/nz will be determined by the resolution and the cube box size. Default is None which means nx/ny/nz are used to determine the grid size.

Raises:

ValueError – If the density matrix dimension does not match the number of spatial orbitals.

Return type:

None

generate_molecular_electrostatic_potential_cube_file(molecular_configuration: MolecularConfiguration, density_operator: RestrictedDensityOperator | UnrestrictedDensityOperator, file_path: Path, component: DensityComponent, nx: int = 80, ny: int = 80, nz: int = 80, resolution: float | None = None) → None

Generate a molecular electrostatic potential (MEP) cube file.

Parameters:

molecular_configuration (MolecularConfiguration) – Configuration holding the PySCF molecule and spatial-orbital count.
density_operator (RestrictedDensityOperator | UnrestrictedDensityOperator) – Restricted or unrestricted density operator.
file_path (Path) – Path where the cube file will be written.
component (DensityComponent) – Which density component to generate (alpha, beta, or total).
nx (int) – Number of grid point divisions in x direction. Note this is function of the molecule’s size; a larger molecule will have a coarser representation than a smaller one for the same value. Conflicts to keyword resolution. default=80
ny (int) – Number of grid point divisions in y direction.
nz (int) – Number of grid point divisions in z direction.
resolution (float | None) – Resolution of the mesh grid in the cube box. If resolution is given in the input, the input nx/ny/nz have no effects. The value of nx/ny/nz will be determined by the resolution and the cube box size. Default is None which means nx/ny/nz are used to determine the grid size.

Raises:

ValueError – If the density matrix dimension does not match the number of spatial orbitals.

Return type:

None

generate_orbital_cube_file(molecular_configuration: MolecularConfiguration, molecular_orbitals: MolecularOrbitals, orbital_index: int, file_path: Path, nx: int = 80, ny: int = 80, nz: int = 80) → None

Generate an orbital cube file.

Parameters:

molecular_configuration (MolecularConfiguration) – Configuration holding the PySCF molecule.
molecular_orbitals (MolecularOrbitals) – Object containing the MO coefficient matrix.
orbital_index (int) – Index of the orbital to generate.
file_path (Path) – Path where the cube file will be written.
nx (int) – Number of grid points along X.
ny (int) – Number of grid points along Y.
nz (int) – Number of grid points along Z.

Raises:

IndexError – If orbital_index is out of range.

Return type:

None

to_density_component_enum(value: Literal['alpha', 'beta', 'total'] | DensityComponent) → DensityComponent

Coerce literal to DensityComponent.

Parameters:: value (Literal['alpha', 'beta', 'total'] | ~qrunch.chemistry.molecule.cube_file_generator.DensityComponent) – Either an enum member or its underlying value string.
Raises:: ValueError – If value is a string and does not match any DensityComponent member.
Return type:: DensityComponent

to_overwriting_policy_enum(value: Literal['overwrite', 'error', 'rename', 'ignore'] | CubeFileOverwritingPolicy) → CubeFileOverwritingPolicy

Coerce literal to CubeFileOverwritingPolicy.

Parameters:: value (Literal['overwrite', 'error', 'rename', 'ignore'] | ~qrunch.chemistry.molecule.cube_file_generator.CubeFileOverwritingPolicy) – Either an enum member or its underlying value string.
Raises:: ValueError – If value is a string and does not match any CubeFileOverwritingPolicy member.
Return type:: CubeFileOverwritingPolicy