libutil: utility functions

General utilities.

haddock.libs.libutil.copy_files_to_dir(paths: Iterable[str | Path], directory: str | Path) → None[source]

Copy files to directory.

Parameters:
  • paths (iterable of paths) – Source files.

  • directory (path) – Where to copy files to.

haddock.libs.libutil.count_heavy_atoms(path: str | Path) → int[source]

Count the non-hydrogen atoms of a PDB file.

Mirrors the filtering done by haddock.modules.analysis.contactmap.contmap.extract_pdb_dt(), which skips hydrogens, so that the count matches the number of coordinates that actually end up in the distance matrix.

Parameters:

path (FilePath) – Path to the PDB file to parse.

Returns:

int – Number of heavy (non-hydrogen) ATOM/HETATM records.

haddock.libs.libutil.cpu_count() → int[source]

Count number of available CPU for the process.

User suggestion, by https://github.com/EricDeveaud

Note: pid 0 == current process

FIXME: from python3.13, better to use os.process_cpu_count()

Returns:

process_ncores (int) – Number of cores allocated to the process pid.

haddock.libs.libutil.extract_keys_recursive(config: MutableMapping[str, Any]) → Generator[str, None, None][source]

Extract keys recursively for the needed modules.

haddock.libs.libutil.get_arch()[source]

Helper function to figure out the architetchure

haddock.libs.libutil.get_available_memory() → float[source]

Get the available system memory in GB.

Returns:

float – Available physical memory in gigabytes (GB).

haddock.libs.libutil.get_cns_executable() → tuple[Path, Path][source]

Locate CNS executable and its Linux variant for grid execution.

Returns:

Tuple of (cns_exec, cns_exec_linux) paths

Raises:

SystemExit – If CNS executable cannot be found

haddock.libs.libutil.get_necessary_memory(models: list) → float[source]

Estimate the memory required to compute the contact map of one model.

The largest of the input models is located by its file size (a cheap stat), and only that one is parsed to obtain the exact number of heavy atoms. The estimate is the peak allocation of the (atoms x atoms) float64 distance matrix built by compute_distance_matrix().

The returned value is the requirement of a single contact map job; the caller must scale it by the number of jobs running concurrently.

Parameters:

models (list) – List of PDBFile objects.

Returns:

float – Estimated memory requirement in gigabytes (GB).

haddock.libs.libutil.get_number_from_path_stem(path: str | Path) → int[source]

Extract tail number from path.

Examples

>>> get_number_from_path_stem('src/file_1.pdb')
>>> 1
>>> get_number_from_path_stem('src/file_3.pdb')
>>> 3
>>> get_number_from_path_stem('file_1231.pdb')
>>> 1231
>>> get_number_from_path_stem('src/file11')
>>> 11
>>> get_number_from_path_stem('src/file_1234_1.pdb')
>>> 1
Parameters:

path (str or Path obj) – The path to evaluate.

Returns:

int – The tail integer of the path.

haddock.libs.libutil.get_prodrg_exec() → tuple[Path | None, Path | None][source]

Locate the prodrg binary and its parameter file.

Returns (None, None) with a warning if the binary cannot be found, allowing the application to start normally. The error will surface later if run_prodrg is actually called.

Returns:

Tuple of (prodrg_exec, prodrg_param) paths, or (None, None) if not found

haddock.libs.libutil.get_result_or_same_in_list(function: Callable[[PT], AnyT], value: PT) → AnyT | list[PT][source]

Return the result if True or the value within a list.

Applies function to value and returns its result if it evaluates to True. Otherwise, return the value within a list.

function should receive a single argument, the value.

haddock.libs.libutil.log_error_and_exit() → Generator[None, None, None][source]

Exit with exception.

haddock.libs.libutil.make_list_if_string(item: str | list[str]) → list[str][source]

Put item into a list.

haddock.libs.libutil.non_negative_int(n: ~typing.Any, exception: type[Exception] = <class 'ValueError'>, emsg: str = '`n` do not satisfies') → int[source]

Transform n in int and returns if compare evaluates to True.

Parameters:
  • n (int-convertable) – Something that can be converted to int.

  • exception (Exception) – The Exception to raise in case n is not a positive integer.

  • emsg (str) – The error message to give to exception. May accept formatting to pass n.

Raises:

ValueError, TypeError – If n cannot be converted to int

haddock.libs.libutil.parse_ncores(n: int | str | None = None, njobs: int | None = None, max_cpus: bool | None = None) → int[source]

Check the number of cores according to HADDOCK3 architecture.

Parameters:
  • n (int or str) – The desired number of cores. If None is given, returns the maximum number of cores allowed, see max_cpus.

  • njobs (int) – The number of jobs to execute. Optional. The number of cores will be compared to njobs.

  • max_cpus (int) – The maximum number of CPUs allowed. If not specified, defaults to the available CPUs minus one.

Raises:

SetupError – If n is not positive or not convertable to int.

Returns:

int – A correct number of cores according to specifications.

haddock.libs.libutil.recursive_convert_paths_to_strings(params: ParamMapT) → ParamMapT[source]

Convert paths to strings recursively over a dictionary.

Parameters:

params (dictionary)

Returns:

dictionary – A copy of the original dictionary with paths converted to strings.

haddock.libs.libutil.recursive_dict_update(d: ParamMapT, u: MutableMapping[str, Any]) → ParamMapT[source]

Update dictionary d according to u recursively.

https://stackoverflow.com/questions/3232943

Returns:

dict – A new dict object with updated key: values. The original dictionaries are not modified.

haddock.libs.libutil.remove_dict_keys(d: MutableMapping[str, Any], keys: Container[str]) → dict[str, Any][source]

Remove keys from dictionary (d).

Returns:

dict – A copy of d dictionary without the keys.

haddock.libs.libutil.remove_folder(folder: str | Path) → None[source]

Remove a folder if it exists.

Parameters:

folder (str or Path) – Path to folder to remove.

haddock.libs.libutil.sort_numbered_paths(*paths: FilePathT) → list[FilePathT][source]

Sort input paths to tail number.

If possible, sort criteria is provided by get_number_from_path_stem(). If paths do not have a numbered tag, sort paths alphabetically.

Parameters:

*inputs (str or pathlib.Path) – Paths to files.

Returns:

list – The sorted pathlist. The original types are not modified. If strings are given, strings are returns, if Paths are given paths are returned.

haddock.libs.libutil.transform_to_list(item: Iterable[AnyT] | AnyT) → list[AnyT] | tuple[AnyT, ...][source]

Put item into a list if not a list already.

If it is set, transforms the set into a list.

If it is a dict, returns a list of the keys.

If it is tuple, returns the tuple.

If a list, returns the same.

Everything else returns item inside a one element list.