-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.
-
-
-