Expandable parameters

Expandable parameter module.

This module contains all logic for reading and preparing expandable parameters.

Expandable parameters are parameters that follow a specific name structure. They can be repeated multiple times (in groups) in the user configuration file while being defined only once in the defaults.yaml files. For example, in the refinement.flexref module there are the parameters:

fle_sta_1_1
fle_end_1_1

For these cases, you can also define in the user configuration file the following:

fle_sta_1_2
fle_end_1_2

The above parameters will be accepted and used in the CNS modules. We say they are the second groupd of the fle1 group. We explain in detail below.

Currently, there are three types of expandable parameters:

1 - Parameters following the name structure:

name_something_1,
name_something_else_1

These two parameters belong to the parameter name name and group 1. The two parameters have the name something and something_else. Therefore, you could define also:

name_something_2
name_something_else_2

Numbers are allowed as long as in combination with word characters, for example: name_something1_2, but not name_something_1_1 because the latter is of the second type.

2 - Parameters following the name structure:

name_something_X_Y
name_else_X_Y

In these cases, the parameter name is nameX, where X is an integer. Y is the number of the group, and something and else are the name of the parameters. Taking example:

fle_sta_1_1
fle_end_1_1

The parameter name is fle1 and the parameters belonging to the groups are sta and end, and the group is either 1.

3 - The simplest parameters in the form of:

param_1

In these cases, you can define param_2, param_3, etc, in the user configuration file despite those are not defined in the defaults.yaml. However, because <name>_<integer> is too much of a simple rule, we need to define in this module which parameters are actualy expandable. If you are developing here look for the type_simplest_ep variable.

Parameters that are expandable to the max number of molecules:

Those are the parameters starting with mol. For example: mol_fix_origin_1, which refers to the fix_origin parameter for molecule 1. These parameters are allowed to expand only to the maximum of input molecules, and at most to the max number of molecules allowed.

haddock.gear.expandable_parameters.belongs_to_multiple_index(param_parts: Sequence[str]) → bool[source]

Assert param belong to multiple index group.

Parameters:

param_parts (list of str) – The parameter name parts after str.split(“_”).

Returns:

boolean – True if the parameter name follows the rules of multiple index expandable parameters.

Rules: - param names have more than 4 parts - the last part is a digit - the part before last is a digit

haddock.gear.expandable_parameters.belongs_to_single_index(param_parts: Sequence[str]) → bool[source]

Assert param belong to single index group.

Parameters:

param_parts (list of str) – The parameter name parts after str.split(“_”).

Returns:

boolean – True if the parameter name follows the rules of single index expandable parameters.

Rules: - param names have more than 2 parts - the last part is a digit - the part before last is not a digit

haddock.gear.expandable_parameters.extract_multiple_index_params(user_config: Iterable[str], param_name: str, group_idx: str) → set[str][source]

Extract the parameters belonging to a group.

See also: belongs_to_multiple_index.

Examples

>>> EM = extract_multiple_index_params

>>> EM({"param_some_1", "param_other_1", "param2", "ppp_ooo"}, "param", "1")
    set()

>>> EM(
    {"param_some_1", "param_other_1", "param_some_2", "param_other_2"},
    "param", "2")
    set()

>>> EM(
    {"param_some_1", "param_other_1", "par_some_2_2", "par_other_2_2"},
    "param", "1")
    {"par_some_2_2", "par_other_2_2"},

>>> EM(
    {"param_some_1", "param_other_1", "par_some_2_2", "par_other_2_2"},
    "par", "2")
    set()

>>> EM(
    {"param_some_1", "param_other_1", "par_some_2_2", "par_other_2_2"},
    "por", "2")
    set()

Parameters:

user_config (dict, or dict.keys(), or similar) – The user configuration file - parameter keys should be parameter names.
param_name (str) – The parameter name of the group to select. For example: c3sym.
group_idx (str) – The number of the group: “1”, “2”, “3”, etc. Only that group number will be selected.

Returns:

set of strings – A set with the selected parameters.

haddock.gear.expandable_parameters.extract_single_index_params(user_config: Iterable[str], param_name: str, group_idx: str) → set[str][source]

Extract the parameters belonging to a group.

Descriminates between parameters of other expandable groups. See: belongs_to_single_index.

Examples

>>> ES = extract_single_index_params

>>> ES({"param_some_1", "param_other_1", "param2", "ppp_ooo"}, "param", "1")
    {"param_some_1", "param_other_1"}

>>> ES(
    {"param_some_1", "param_other_1", "param_some_2", "param_other_2"},
    "param", "2")
    {"param_some_2", "param_other_2"}

>>> ES(
    {"param_some_1", "param_other_1", "par_some_2_2", "par_other_2_2"},
    "param", "1")
    {"param_some_1", "param_other_1"}

>>> ES(
    {"param_some_1", "param_other_1", "par_some_2_2", "par_other_2_2"},
    "par", "2")
    set()

>>> ES(
    {"param_some_1", "param_other_1", "par_some_2_2", "par_other_2_2"},
    "por", "2")
    set()

Parameters:

user_config (dict, or dict.keys(), or similar) – The user configuration file - parameter keys should be parameter names.
param_name (str) – The parameter name of the group to select. For example: c3sym.
group_idx (str) – The number of the group: “1”, “2”, “3”, etc. Only that group number will be selected.

Returns:

set of strings – A set with the selected parameters.

haddock.gear.expandable_parameters.get_mol_parameters(config: Iterable[str]) → set[str][source]: Identify expandable mol parameters.

haddock.gear.expandable_parameters.get_multiple_index_groups(config: ~typing.MutableMapping[str, ~typing.Any], *, belongs_to_group: ~typing.Callable[[~typing.Sequence[str]], bool] = <function belongs_to_multiple_index>, make_param_name: ~typing.Callable[[~typing.Sequence[str]], tuple[str, str]] = <function make_param_name_multiple_index>, rejoin_parts: ~typing.Callable[[~typing.Sequence[str]], str] = <function rejoin_parts_multiple_index>, minimum: int = 2, reference: bool = True) → dict[tuple[str, str], Any]

Get parameter blocks with multiple indexes.

These blocks of params apply, for example, to different molecules. That’s why they have two looping indexes: one for the molecule and other for the group.

This block of parameters follow the rule:

Where the actual param name is paramN, where N is an integer.

<something> be can any combination of alphanumeric chars and underscores.

<G> is the number of the group, the will be incremented as we expand.

These belong to the same parameter (param1) of the group 1:

param_something_1_1
param_something2_1_1
param_something_else_1_1
param_something4_1

You could expand these with:

param_something_1_2
param_something2_1_2
param_something_else_1_2
param_something4_2

When used to read the modules’ default configuration we expect the <digit> to be only “_1”. But having <digit> allows to identify blocks from the user configuration.

Returns a dictionary in the form of:

{("param1", "1"): {
    "something1", "something2", "something_else", "something4"}

Parameters:

config (dict) – Where keys are the parameter names. The values are not important.
minimum (int) – Consider only the groups with at least minimum parameters.
reference (bool) – Whether reading a default config file or not. If true, only groups ending with “1” will be considered. This avoids capturing parameters for molecules, such as “mol_fix_origin_1”, “mol_fix_origin_2”, etc.

Returns:

dictionary ({(tuple): dict})

haddock.gear.expandable_parameters.get_single_index_groups(config: ~typing.MutableMapping[str, ~typing.Any], *, belongs_to_group: ~typing.Callable[[~typing.Sequence[str]], bool] = <function belongs_to_single_index>, make_param_name: ~typing.Callable[[~typing.Sequence[str]], tuple[str, str]] = <function make_param_name_single_index>, rejoin_parts: ~typing.Callable[[~typing.Sequence[str]], str] = <function rejoin_parts_single_index>, minimum: int = 2, reference: bool = True) → dict[tuple[str, str], Any]

Get single indexed blocks from a configuration.

Block parameters follow the rule <preffix>_<something>_<group>.

These belong to the same parameter (param) of the group 1:

param_something1_1
param_something2_1
param_something_else_1
param_something4_1

You could expand these with:

param_something1_2
param_something2_2
param_something_else_2
param_something4_2

When used to read the modules’ default configuration we expect the <group> to be only “_1”. But having <group> allows to identify blocks from the user configuration. See reference parameter.

When we execute this function, we want to know:

param, the parameter name preffix
how many parameters exist of the block (something1, something2, …)
_1, defines the number of the block

Returns a dictionary in the form of:

{
    ("param", "1"): {
        "something1", "something2",
        "something_else", "something4"
        },
    ("otherparam", "1"): {"somename", "othername"},
    }

Parameters:

config (dictionary) – Where keys are the parameter names. The values are not important.
minimum (int) – Consider only the groups with at least minimum parameters.
reference (bool) – Whether reading a default config file or not. If true, only groups ending with “1” will be considered. This avoids capturing parameters for molecules, such as “mol_fix_origin_1”, “mol_fix_origin_2”, etc.

Returns:

dictionary - {tuple (dict})

haddock.gear.expandable_parameters.get_trail_index(param: str) → str | None[source]

Get the trail index if underscored.

Examples

has_trail_index(‘some_parameter_1’) >>> ‘1’

has_trail_index(‘some_parameter1’) >>> None

has_trail_index(‘some_parameter_1_1’) >>> ‘1’

has_trail_index(‘some_parameter_1-1’) >>> None

has_trail_index(‘some_parameter’) >>> None

Parameters:: param (str) – A parameter name.
Returns:: str or None – The trail index if exist. None if not found.

haddock.gear.expandable_parameters.is_mol_parameter(param: str) → bool[source]: Identify if a parameter is a mol parameter.

haddock.gear.expandable_parameters.make_param_name_multiple_index(param_parts: Sequence[SupportsAddT]) → tuple[SupportsAddT, SupportsAddT][source]

Make the key name from param parts.

For example, (“param”, “tag”, “2”, “1”) -> (“param2”, “1”).

haddock.gear.expandable_parameters.make_param_name_single_index(param_parts: Sequence[AnyT]) → tuple[AnyT, AnyT][source]

Make the key name from param parts.

For example, (“param”, “tag”, “1”) -> (“param”, “1”).

haddock.gear.expandable_parameters.populate_mol_parameters_in_module(params: MutableMapping[str, Any], num_mols: int, defaults: MutableMapping[str, Any]) → None[source]

Populate parameters dictionary with the needed molecule mol_ parameters.

The mol_ prefixed parameters is a subclass of the expandable parameters.

See haddock.gear.expandable_parameters.

Modules require these parameters to be repeated for the number of input molecules.

This function adds mol_ parameters to the user input parameters, one per each molecule and for those which a values has not been added yet.

Parameters:: modules_params (dict) – A dictionary of parameters.
Returns:: None – Alter the dictionary in place.

haddock.gear.expandable_parameters.read_mol_parameters(user_config: MutableMapping[str, Any], default_groups: Iterable[str], max_mols: int = 20) → set[str][source]

Read the mol parameters in the user_config following expectations.

Parameters:

user_config (dict) – The user configuration dictionary.
default_groups (dict or set.) – The mol parameters present in the default configuration file for the specific module. These are defined by get_mol_parameters.
max_mols (int) – HADDOCK3 has a limit in the number of different molecules it accepts for a calculation. Expandable parameters affecting molecules should not be allowed to go beyond that number. Defaults to core.default.max_molecules_allowed.

Returns:

set – The allowed parameters according to the default config and the max allowed molecules.

haddock.gear.expandable_parameters.read_multiple_idx_groups_user_config(user_config: ~typing.Iterable[str], default_groups: dict[tuple[str, str], ~typing.Any], *, get_user_groups: ~typing.Callable[[...], dict[tuple[str, str], ~typing.Any]] = functools.partial(<function _get_groups>, belongs_to_group=<function belongs_to_multiple_index>, make_param_name=<function make_param_name_multiple_index>, rejoin_parts=<function rejoin_parts_multiple_index>), extract_params: ~typing.Callable[[...], set[str]] = <function extract_multiple_index_params>, _emsg_no_group: str = "The parameter block '{}_*_{}_*' is not a valid expandable parameter.", _emsg_unexpected_params: str = "These parameters do not belong to the block '{}_*_{}_*': {!r}.") → tuple[set[str], dict[str, int]]

Read multiple indexed groups in user config.

Parameters:

user_config (dict) – The user configuration dictionary.
default_groups (dict) – The groups present in the default configuration file for the specific module. This is the dictionary created by get_multiple_index_groups.

Returns:

set – A set with the new parameters in the user configuration file that are acceptable according to the expandable rules.

haddock.gear.expandable_parameters.read_simplest_expandable(config: Iterable[str], expparams: Iterable[str]) → set[str][source]

Read expandable parameters from config file of the type param_1.

Parameters:

config (dict, dict.keys, set, or alike) – The user configuration file.
expparams (dict, dict.keys, set, or alike) – The parameter names that should be considered as expandable. Usually, this is a module subdictionary of type_simplest_ep.

Returns:

set of str – The parameters in config that comply with expparams.

haddock.gear.expandable_parameters.read_single_idx_groups_user_config(user_config: ~typing.Iterable[str], default_groups: dict[tuple[str, str], ~typing.Any], *, get_user_groups: ~typing.Callable[[...], dict[tuple[str, str], ~typing.Any]] = functools.partial(<function _get_groups>, belongs_to_group=<function belongs_to_single_index>, make_param_name=<function make_param_name_single_index>, rejoin_parts=<function rejoin_parts_single_index>), extract_params: ~typing.Callable[[...], set[str]] = <function extract_single_index_params>, _emsg_no_group: str = "The parameter block '{}_*_{}' is not a valid expandable parameter.", _emsg_unexpected_params: str = "These parameters do not belong to the block '{}_*_{}': {!r}.") → tuple[set[str], dict[str, int]]

Read single indexed groups in user config.

Parameters:

user_config (dict) – The user configuration dictionary.
default_groups (dict) – The groups present in the default configuration file for the specific module. This is the dictionary created by, get_single_index_groups.

Returns:

set – A set with the new parameters in the user configuration file that are acceptable according to the expandable rules.

haddock.gear.expandable_parameters.rejoin_parts_multiple_index(param_parts: Sequence[str]) → str[source]: Join parameter name parts.

haddock.gear.expandable_parameters.rejoin_parts_single_index(param_parts: Sequence[str]) → str[source]: Join parameter name parts.

haddock.gear.expandable_parameters.remove_ghost_groups(groups: dict[tuple[str, str], Any]) → dict[tuple[str, str], Any][source]

Remove ghost groups from dictionary.

Ghost groups are parameters that are defined in the defaults in a manner that they look they are already expanded. For example:

mol_shape_1
mol_shape_2
mol_shape_3
mol_fix_origin_1
mol_fix_origin_2
mol_fix_origin_3

These integer suffix refer to the input molecules and not to expandable groups.

Parameters:: groups (dict) – A dictionary containing the groups. For example as those created by get_single_index_groups.

haddock.gear.expandable_parameters.remove_trail_idx(param: str) → str[source]

Remove the trailing integer from a parameter.

If trail is defined by an underscore “_”.

Examples

remove_trail_idx(‘some_parameter_1’) >>> ‘some_parameter’

remove_trail_idx(‘some_parameter’) >>> ‘some_parameter’

remove_trail_idx(‘parameter’) >>> ‘parameter’

Parameters:: param (str) – A parameter name.