pyef.validation

Validation utilities for pyEF.

This module provides centralized validation functions for input parameters, file paths, and data formats. All validation functions raise ValueError with helpful error messages that include examples and references to documentation.

Module Contents

Functions

get_atom_count_from_xyz(→ int)

Parse the number of atoms from an XYZ file.

validate_charge_type(→ None)

Validate that a charge type is in the set of supported schemes.

filter_charge_types_for_multipole(→ List[str])

Filter charge types to only those that work with multipole analysis.

filter_charge_types_for_monopole(→ List[str])

Filter charge types to only those that work with monopole analysis.

check_path_exists(→ None)

Check if a file or directory path exists.

validate_numeric_range(→ None)

Validate that a numeric parameter is within acceptable range.

validate_atom_indices(→ None)

Validate that atom indices are within structure bounds.

check_index_overlap(→ None)

Check if two sets of indices have any overlap.

Attributes

VALID_CHARGE_TYPES

VALID_MULTIPOLE_CHARGE_TYPES

VALID_CHARGE_TYPES
VALID_MULTIPOLE_CHARGE_TYPES
get_atom_count_from_xyz(xyz_path: str) → int[source]

Parse the number of atoms from an XYZ file.

Parameters:

xyz_path (str) – Path to the XYZ file

Returns:

Number of atoms in the structure

Return type:

int

Raises:

ValueError – If the file doesn’t exist or has invalid format

validate_charge_type(charge_type: str, context: str = '') → None[source]

Validate that a charge type is in the set of supported schemes.

Parameters:

  • charge_type (str) – The charge partitioning scheme to validate

  • context (str, optional) – Additional context for the error message

Raises:

ValueError – If the charge type is not valid

filter_charge_types_for_multipole(charge_types: str | List[str], context: str = '') → List[str][source]

Filter charge types to only those that work with multipole analysis.

Only Hirshfeld, Hirshfeld_I, and Becke are supported for multipole analysis. This function validates the input, warns about unsupported types, and returns only the valid ones.

Parameters:

  • charge_types (str or list of str) – Charge partitioning scheme(s) to validate

  • context (str, optional) – Additional context for warning/error messages

Returns:

Filtered list containing only valid multipole charge types. Returns empty list if no valid types are found.

Return type:

list of str

Warning

Prints warnings for any charge types that don’t support multipole analysis

filter_charge_types_for_monopole(charge_types: str | List[str], context: str = '') → List[str][source]

Filter charge types to only those that work with monopole analysis.

All charge types in VALID_CHARGE_TYPES are supported for monopole analysis. This function validates the input and returns only valid types.

Parameters:

  • charge_types (str or list of str) – Charge partitioning scheme(s) to validate

  • context (str, optional) – Additional context for warning/error messages

Returns:

Filtered list containing only valid monopole charge types. Returns empty list if no valid types are found.

Return type:

list of str

Warning

Prints warnings for any invalid charge types

check_path_exists(path: str, path_type: str = 'file', context: str = '') → None[source]

Check if a file or directory path exists.

Parameters:

  • path (str) – Path to check

  • path_type (str) – Either “file” or “directory”

  • context (str, optional) – Additional context for the error message

Raises:

ValueError – If the path does not exist

validate_numeric_range(value: Any, name: str, min_val: float | None = None, max_val: float | None = None, allowed_values: List | None = None, context: str = '') → None[source]

Validate that a numeric parameter is within acceptable range.

Parameters:

  • value (Any) – The value to validate

  • name (str) – Parameter name for error messages

  • min_val (float, optional) – Minimum allowed value (inclusive)

  • max_val (float, optional) – Maximum allowed value (inclusive)

  • allowed_values (list, optional) – List of specific allowed values

  • context (str, optional) – Additional context for error message

Raises:

ValueError – If the value is not numeric or out of range

validate_atom_indices(indices: int | List[int], atom_count: int, context: str = '', xyz_path: str = '') → None[source]

Validate that atom indices are within structure bounds.

Parameters:

  • indices (int or list of int) – Atom index or list of atom indices to validate (0-indexed)

  • atom_count (int) – Total number of atoms in the structure

  • context (str, optional) – Description of where indices are used (for error message)

  • xyz_path (str, optional) – Path to XYZ file for reference in error message

Raises:

ValueError – If any index is out of bounds

check_index_overlap(indices1: List[int], indices2: List[int], name1: str = 'first set', name2: str = 'second set', context: str = '') → None[source]

Check if two sets of indices have any overlap.

Parameters:

  • indices1 (list of int) – First set of atom indices

  • indices2 (list of int) – Second set of atom indices

  • name1 (str) – Name of first set for error message

  • name2 (str) – Name of second set for error message

  • context (str, optional) – Additional context for error message

Raises:

ValueError – If there is any overlap between the sets