pysoftk.htp_tools package

Submodules

pysoftk.htp_tools.calculator_htp module

class pysoftk.htp_tools.calculator_htp.Htp(xtb_command='xtb', ending='.xyz')[source]

Bases: object

Class enabling High-throughput quantum chemistry calculations using xtb.

This class facilitates running xtb calculations (like geometry optimizations) on multiple molecular structures organized in subdirectories. It automatically scans a specified main directory for subdirectories, checks if each contains a single geometry file (‘.xyz’ by default), and then runs the requested xtb calculation method (GFN or GFN-FF) in parallel within each valid subdirectory.

It intelligently locates the ‘xtb’ executable, either by searching the system’s PATH environment variable (common for Conda installations) or by using a direct path provided during initialization.

xtb_executable_path

The absolute path to the ‘xtb’ executable that was found and verified during initialization. This path is used for all subsequent calculation calls.

Type:

str

ending

The default file extension (e.g., ‘.xyz’) used when searching for geometry files within subdirectories. This can be customized during initialization but defaults to ‘.xyz’ as used by the primary methods.

Type:

str

Raises:

FileNotFoundError – During initialization (__init__) if the specified ‘xtb_command’ cannot be found as an executable in the system PATH, nor resolved as a direct valid file path.

Note

  • Requires the ‘tqdm’ library for progress bars (pip install tqdm).

  • Requires a working installation of ‘xtb’ accessible either via the system PATH or by providing a direct path to the executable.

  • Assumes a directory structure where each calculation is contained within its own subdirectory under a main directory, and each calculation subdirectory contains exactly one input geometry file with the expected ending (e.g., ‘molecule.xyz’).

htp_xtb_ff(directory, max_work, num_cores, threshold='crude')[source]

Runs parallel GFN-FF optimizations on structures in subdirectories.

This method orchestrates high-throughput GFN-FF calculations. It mirrors the functionality of htp_xtb_gfn but schedules xtb_ff tasks instead, utilizing the GFN-FF force field method in xtb.

Parameters:

  • directory (str) – Path to the main directory containing subdirectories for calculations.

  • max_work (int) – Maximum number of concurrent xtb processes (worker threads).

  • num_cores (int) – Number of CPU cores for each individual xtb GFN-FF process.

  • threshold (str, optional) – Optimization convergence threshold passed to xtb_ff. Defaults to “crude”.

Returns:

Executes calculations and prints progress; does not return a value.

Return type:

None

htp_xtb_gfn(directory, max_work, num_cores, threshold='crude')[source]

Runs parallel GFN-XTB optimizations on structures in subdirectories.

This method orchestrates the high-throughput process. It scans the specified directory for immediate subdirectories. For each subdirectory that contains exactly one ‘.xyz’ file, it schedules an xtb_gfn calculation using a ThreadPoolExecutor for parallel execution. Progress is displayed using tqdm.

Parameters:

  • directory (str) – The path to the main directory. This directory should contain subdirectories, each holding one calculation setup (specifically, one ‘.xyz’ file).

  • max_work (int) – The maximum number of concurrent xtb processes to run in parallel. This corresponds to the number of worker threads in the pool.

  • num_cores (int) – The number of CPU cores allocated to each individual xtb process (passed via the –parallel flag to xtb_gfn).

  • threshold (str, optional) – The geometry optimization convergence threshold level passed down to each xtb_gfn call. Defaults to “crude”.

Returns:

This method primarily executes side effects (running calculations, printing output, creating files) and does not return a value.

Return type:

None

static xtb_ff(xtb_path, xyz_filename, target_dir, num_cores=None, threshold=None)[source]

Executes a single GFN-FF geometry optimization via subprocess.

Similar to xtb_gfn, but performs a GFN-FF (force field) optimization by adding the –gfnff flag to the xtb command line. Output is redirected to ‘output_ff.log’ within the target_dir.

Parameters:

  • xtb_path (str) – The absolute path to the verified xtb executable.

  • xyz_filename (str) – The filename (basename) of the input geometry file within target_dir.

  • target_dir (str) – The absolute path to the directory where the calculation should run (cwd).

  • num_cores (int, optional) – Number of processor cores for xtb (–parallel). Defaults to 1.

  • threshold (str, optional) – Convergence threshold for optimization (–opt). Defaults to “crude”.

Returns:

  • str – The absolute path to the output log file ‘output_ff.log’ within target_dir.

  • Side Effects

  • ————

    • Creates or overwrites the file “output_ff.log” in target_dir.

    • Runs an external xtb process with the –gfnff flag.

    • Prints warnings/errors similar to xtb_gfn.

  • - Appends error details to “output_ff.log” upon failure.

static xtb_gfn(xtb_path, xyz_filename, target_dir, num_cores=None, threshold=None)[source]

Executes a single GFN-XTB geometry optimization via subprocess.

This static method is designed to be called as a target function, often in parallel (e.g., via ThreadPoolExecutor). It constructs and runs the xtb command line for a GFN-XTB optimization (–opt) within the specified target_dir. Output is redirected to ‘output.log’ within that directory.

Parameters:

  • xtb_path (str) – The absolute path to the verified xtb executable.

  • xyz_filename (str) – The filename (basename, e.g., “molecule.xyz”) of the input geometry file. This file is expected to exist within target_dir.

  • target_dir (str) – The absolute path to the directory where the calculation should run. The xtb command will be executed with this directory as its current working directory (cwd).

  • num_cores (int, optional) – The number of processor cores the xtb calculation should use (–parallel flag). If None, defaults to 1.

  • threshold (str, optional) – The convergence threshold level for the geometry optimization (–opt flag value, e.g., “crude”, “normal”, “tight”). If None, defaults to “crude”.

Returns:

  • str – The absolute path to the output log file created within target_dir (e.g., “/path/to/target_dir/output.log”).

  • Side Effects

  • ————

    • Creates or overwrites the file “output.log” in target_dir.

    • Runs an external xtb process.

    • Prints warning messages to standard output if the xtb process – returns a non-zero exit code or if a Python exception occurs during

    the subprocess execution.

  • - Appends error details (Python exception, stderr from xtb) to the – “output.log” file upon failure.

Module contents