+Advanced Hyperparameters Set Up
+For multi-component systems, the configurational space can be highly complicated.
+One may want to use different hyper-parameters and cutoffs for different interactions,
+or do constraint optimisation for hyper-parameters.
+To use more hyper-parameters, we need special kernel function that can differentiate different
+pairs, triplets and other descriptors and determine which number to use for what interaction.
+This kernel can be enabled by using the hyps_mask argument of the GaussianProcess class.
+It contains multiple arrays to describe how to break down the array of hyper-parameters and
+apply them when computing the kernel. Detail descriptions of this argument can be seen in
+kernel/mc_sephyps.py.
+The ParameterHelper class is to generate the hyps_mask with a more human readable interface.
+Example:
+>>> pm = ParameterHelper(species=['C', 'H', 'O'],
+... kernels={'twobody':[['*', '*'], ['O','O']],
+... 'threebody':[['*', '*', '*'],
+... ['O','O', 'O']]},
+... parameters={'twobody0':[1, 0.5, 1], 'twobody1':[2, 0.2, 2],
+... 'threebody0':[1, 0.5], 'threebody1':[2, 0.2],
+... 'cutoff_threebody':1},
+... constraints={'twobody0':[False, True]})
+>>> hm = pm.as_dict()
+>>> kernels = hm['kernels']
+>>> gp_model = GaussianProcess(kernels=kernels,
+... hyps=hyps, hyps_mask=hm)
+
+
In this example, four atomic species are involved. There are many kinds
+of twobodys and threebodys. But we only want to use eight different signal variance
+and length-scales.
+In order to do so, we first define all the twobodys to be group “twobody0”, by
+listing “-” as the first element in the twobody argument. The second
+element O-O is then defined to be group “twobody1”. Note that the order
+matters here. The later element overrides the ealier one. If
+twobodys=[[‘O’, ‘O’], [‘*’, ‘*’]], then all twobodys belong to group “twobody1”.
+Similarly, O-O-O is defined as threebody1, while all remaining ones
+are left as threebody0.
+The hyperpameters for each group is listed in the order of
+[sig, ls, cutoff] in the parameters argument. So in this example,
+O-O interaction will use [2, 0.2, 2] as its sigma, length scale, and
+cutoff.
+For threebody, the parameter arrays only come with two elements. So there
+is no cutoff associated with threebody0 or threebody1; instead, a universal
+cutoff is used, which is defined as ‘cutoff_threebody’.
+The constraints argument define which hyper-parameters will be optimized.
+True for optimized and false for being fixed.
+Here are a couple more simple examples.
+Define a 5-parameter 2+3 kernel (1, 0.5, 1, 0.5, 0.05)
+>>> pm = ParameterHelper(kernels=['twobody', 'threebody'],
+... parameters={'sigma': 1,
+... 'lengthscale': 0.5,
+... 'cutoff_twobody': 2,
+... 'cutoff_threebody': 1,
+... 'noise': 0.05})
+
+
Define a 5-parameter 2+3 kernel (1, 1, 1, 1, 0.05)
+>>> pm = ParameterHelper(kernels=['twobody', 'threebody'],
+... parameters={'cutoff_twobody': 2,
+... 'cutoff_threebody': 1,
+... 'noise': 0.05},
+... ones=ones,
+... random=not ones)
+
+
Define a 9-parameter 2+3 kernel
+>>> pm = ParameterHelper()
+>>> pm.define_group('specie', 'O', ['O'])
+>>> pm.define_group('specie', 'rest', ['C', 'H'])
+>>> pm.define_group('twobody', '**', ['*', '*'])
+>>> pm.define_group('twobody', 'OO', ['O', 'O'])
+>>> pm.define_group('threebody', '***', ['*', '*', '*'])
+>>> pm.define_group('threebody', 'Oall', ['O', 'O', 'O'])
+>>> pm.set_parameters('**', [1, 0.5])
+>>> pm.set_parameters('OO', [1, 0.5])
+>>> pm.set_parameters('Oall', [1, 0.5])
+>>> pm.set_parameters('***', [1, 0.5])
+>>> pm.set_parameters('cutoff_twobody', 5)
+>>> pm.set_parameters('cutoff_threebody', 4)
+
+
See more examples in functions ParameterHelper.define_group , ParameterHelper.set_parameters,
+and in the tests tests/test_parameters.py
+If you want to add in a new hyperparameter set to an already-existing GP, you can perform the
+following steps:
+>> hyps_mask = pm.as_dict()
+>> hyps = hyps_mask[‘hyps’]
+>> kernels = hyps_mask[‘kernels’]
+>> gp_model.update_kernel(kernels, ‘mc’, hyps_mask)
+>> gp_model.hyps = hyps
+
+-
+class flare.utils.parameter_helper.ParameterHelper(hyps_mask=None, species=None, kernels={}, cutoff_groups={}, parameters=None, constraints={}, allseparate=False, random=False, ones=False, verbose='WARNING')
+A helper class to construct the hyps_mask dictionary for AtomicEnvironment
+, GaussianProcess and MappedGaussianProcess
+
+- Parameters
+
+hyps_mask (dict) – Not implemented yet
species (dict, list) – Define specie groups
kernels (dict, list) – Define kernels and groups for the kernels
cutoff_groups (dict) – Define different cutoffs for different species
parameters (dict) – Define signal variance, length scales, and cutoffs
constraints (dict) – If listed as False, the cooresponding hyperparmeters
+will not be trained
allseparate (bool) – If True, define each type pair/triplet into a
+separate group.
random (bool) – If True, randomized all signal variances and lengthscales
one (bool) – If True, set all signal variances and lengthscales to one
verbose (str) – Level to print with “ERROR”, “WARNING”, “INFO”, “DEBUG”
+
+
+the species is an optional input. It can be left as None if the user only wants
+to set up one group of hyper-parameters for each kernel.
the kernels can be defined along with or without groups. But the later mode
+is not compatible with the allseparate flag.
+>>> kernels=['twobody', 'threebody'],
+
+
or
+>>> kernels={'twobody':[['*', '*'], ['O','O']],
+... 'threebody':[['*', '*', '*'],
+... ['O','O', 'O']]},
+
+
Current options for the kernels are twobody, threebody and manybody (based on coordination number).
+See format of species, kernels (dict), and cutoff_groups in list_groups() function.
See format of parameters and constraints in list_parameters() function.
+
+-
+all_separate_groups(group_type)
+Separate all possible types of twobodys, threebodys, manybody.
+One type per group.
+
+- Parameters
+group_type (str) – “specie”, “twobody”, “threebody”, “cut3b”, “manybody”
+
+
+
+
+-
+as_dict()
+Dictionary representation of the mask. The output can be used for AtomicEnvironment
+or the GaussianProcess
+
+
+
+-
+define_group(group_type, name, element_list, parameters=None, atomic_str=False)
+Define specie/twobody/threebody/3b cutoff/manybody group
+
+- Parameters
+
+group_type (str) – “specie”, “twobody”, “threebody”, “cut3b”, “manybody”
name (str) – the name use for indexing. can be anything but “*”
element_list (list) – list of elements
parameters (list) – corresponding parameters for this group
atomic_str (bool) – whether the elements in element_list are
+specified by group names or periodic table element names.
+
+The function is helped to define different groups for specie/twobody/threebody
+/3b cutoff/manybody terms. This function can be used for many times.
+The later one always overrides the former one.
+The name of the group has to be unique string (but not “*”), that
+define a group of species or twobodys, etc. If the same name is used,
+in two function calls, the definitions of the group will be merged.
+Both calls will be effective.
+element_list has to be a list of atomic elements, or a list of
+specie group names (which should be defined in previous calls), or “*”.
+“*” will loop the function over all previously defined species.
+It has to be two elements for twobody/3b cutoff/manybody term, or
+three elements for threebody. For specie group definition, it can be
+as many elements as you want.
+If multiple define_group calls have conflict with element, the later one
+has higher priority. For example, twobody 1-2 are defined as group1 in
+the first call, and as group2 in the second call. In the end, the twobody
+will be left as group2.
+Example 1:
+>>> define_group('specie', 'water', ['H', 'O'])
+>>> define_group('specie', 'salt', ['Cl', 'Na'])
+
+
They define H and O to be group water, and Na and Cl to be group salt.
+Example 2.1:
+>>> define_group('twobody', 'in-water', ['H', 'H'], atomic_str=True)
+>>> define_group('twobody', 'in-water', ['H', 'O'], atomic_str=True)
+>>> define_group('twobody', 'in-water', ['O', 'O'], atomic_str=True)
+
+
Example 2.2:
+>>> define_group('twobody', 'in-water', ['water', 'water'])
+
+
The 2.1 is equivalent to 2.2.
+Example 3.1:
+>>> define_group('specie', '1', ['H'])
+>>> define_group('specie', '2', ['O'])
+>>> define_group('twobody', 'Hgroup', ['H', 'H'], atomic_str=True)
+>>> define_group('twobody', 'Hgroup', ['H', 'O'], atomic_str=True)
+>>> define_group('twobody', 'OO', ['O', 'O'], atomic_str=True)
+
+
Example 3.2:
+>>> define_group('specie', '1', ['H'])
+>>> define_group('specie', '2', ['O'])
+>>> define_group('twobody', 'Hgroup', ['H', '*'], atomic_str=True)
+>>> define_group('twobody', 'OO', ['O', 'O'], atomic_str=True)
+
+
Example 3.3:
+>>> list_groups('specie', ['H', 'O'])
+>>> define_group('twobody', 'Hgroup', ['H', '*'])
+>>> define_group('twobody', 'OO', ['O', 'O'])
+
+
Example 3.4:
+>>> list_groups('specie', ['H', 'O'])
+>>> define_group('twobody', 'OO', ['*', '*'])
+>>> define_group('twobody', 'Hgroup', ['H', '*'])
+
+
3.1 to 3.4 are all equivalent.
+
+
+
+-
+fill_in_parameters(group_type, random=False, ones=False, universal=False)
+Separate all possible types of twobodys, threebodys, manybody.
+One type per group. And fill in either universal ls and sigma from
+pre-defined parameters from set_parameters(“sigma”, ..) and set_parameters(“ls”, ..)
+or random parameters if random is True.
+
+- Parameters
+
+group_type (str) – “specie”, “twobody”, “threebody”, “cut3b”, “manybody”
definition_list (list, dict) – list of elements
+
+
+
+
+-
+find_group(group_type, element_list, atomic_str=False)
+find the group that contains the input pair
+
+- Parameters
+
+group_type (str) – species, twobody, threebody, cut3b, manybody
element_list (list) – list of elements for a pair/triplet/coordination-pair
atomic_str (bool) – whether the elements in element_list are
+specified by group names or periodic table element names.
+- Return type
+name (str)
+
+
+
+
+-
+static from_dict(hyps_mask, verbose=False, init_spec=[])
+convert dictionary mask to HM instance
+This function is not tested yet
+
+
+
+-
+list_groups(group_type, definition_list)
+define groups in batches.
+
+- Parameters
+
+group_type (str) – “specie”, “twobody”, “threebody”, “cut3b”, “manybody”
definition_list (list, dict) – list of elements
+
+This function runs define_group in batch. Please first read
+the manual of define_group.
+If the definition_list is a list, it is equivalent to
+executing define_group through the definition_list.
+>>> for all terms in the list:
+>>> define_group(group_type, group_type+'n', the nth term in the list)
+
+
So the first twobody defined will be group twobody0, second one will be
+group twobody1. For specie, it will define all the listed elements as
+groups with only one element with their original name.
+If the definition_list is a dictionary, it is equivalent to
+>>> for k, v in the dict:
+>>> define_group(group_type, k, v)
+
+
It is not recommended to use the dictionary mode, especially when
+the group definitions are conflicting with each other. There is no
+guarantee that the priority order is the same as you want.
+Unlike ParameterHelper.define_group(), it can only be called once for each
+group_type, and not after any ParameterHelper.define_group() calls.
+
+
+
+-
+list_parameters(parameter_dict: dict, constraints: dict = {})
+Define many groups of parameters
+
+- Parameters
+-
+
+
+Example:
+>>> parameter_dict={"group_name":[sig, ls, cutoffs], ...}
+>>> constraints={"group_name":[True, False, False], ...}
+
+
The name of parameters can be the group name previously defined in
+define_group or list_groups function. Aside from the group name,
+noise, cutoff_twobody, cutoff_threebody, and
+cutoff_manybody are reserved for noise parmater
+and universal cutoffs, while sigma and lengthscale are
+reserved for universal signal variances and length scales.
+For non-reserved keys, the value should be a list of 2 to 3 elements,
+corresponding to the sigma, lengthscale and cutoff (if the third one
+is defined). For reserved keys, the value should be a float number.
+The parameter_dict and constraints should use the same set of keys.
+If a key in constraints is not used in parameter_dict, it will be ignored.
+The value in the constraints can be either a single bool, which apply
+to all parameters, or list of bools that apply to each parameter.
+
+
+
+-
+set_constraints(name, opt)
+Set the parameters for certain group
+
+- Parameters
+-
+
+
+The name of parameters can be the group name previously defined in
+define_group or list_groups function. Aside from the group name,
+noise, cutoff_twobody, cutoff_threebody, and
+cutoff_manybody are reserved for noise parmater
+and universal cutoffs, while sigma and lengthscale are
+reserved for universal signal variances and length scales.
+The optimization flag can be a single bool, which apply to all
+parameters under that name, or list of bools that apply to each
+parameter.
+
+
+
+-
+set_parameters(name, parameters, opt=True)
+Set the parameters for certain group
+
+- Parameters
+
+name (str) – name of the patermeters
parameters (list) – the sigma, lengthscale, and cutoff of each group.
opt (bool, list) – whether to optimize the parameter or not
+
+The name of parameters can be the group name previously defined in
+define_group or list_groups function. Aside from the group name,
+noise, cutoff_twobody, cutoff_threebody, and
+cutoff_manybody are reserved for noise parmater
+and universal cutoffs, while sigma and lengthscale are
+reserved for universal signal variances and length scales.
+The parameter should be a list of 2-3 elements, for sigma,
+lengthscale (and cutoff if the third one is defined).
+The optimization flag can be a single bool, which apply to all
+parameters, or list of bools that apply to each parameter.
+
+
+
+-
+summarize_group(group_type)
+Sort and combine all the previous definition to internal varialbes
+
+- Parameters
+group_type (str) – species, twobody, threebody, cut3b, manybody
+
+
+
+
+
+
+-
+flare.utils.parameter_helper.nprandom()
+random(size=None)
+Return random floats in the half-open interval [0.0, 1.0). Alias for
+random_sample to ease forward-porting to the new random API.
+
+
+
