criterion module¶

Acquisition criterion for which the optimum would improve the regression model.

An acquisition criterion (also called infill criterion) is a function taking a model input value and returning a value of interest to maximize (default option) or minimize according to the meaning of the acquisition criterion.

Then, the input value optimizing this criterion can be used to enrich the dataset used by a machine learning algorithm in its training stage. This is the purpose of adaptive learning.

This notion of acquisition criterion is implemented through the MLDataAcquisitionCriterion class which is built from a MLSupervisedAlgo and inherits from MDOFunction.

class gemseo_mlearning.adaptive.criterion.MLDataAcquisitionCriterion(algo_distribution, **options)[source]¶

Bases: MDOFunction

Acquisition criterion.

# noqa: D205 D212 D415

Parameters:

algo_distribution (MLRegressorDistribution) – The distribution of a machine learning algorithm.
**options (MLDataAcquisitionCriterionOptionType) – The acquisition criterion options.

class ApproximationMode(value)¶

Bases: StrEnum

The approximation derivation modes.

COMPLEX_STEP = 'complex_step'¶: The complex step method used to approximate the Jacobians by perturbing each variable with a small complex number.

FINITE_DIFFERENCES = 'finite_differences'¶: The finite differences method used to approximate the Jacobians by perturbing each variable with a small real number.

class ConstraintType(value)¶

Bases: StrEnum

The type of constraint.

EQ = 'eq'¶: The type of function for equality constraint.

INEQ = 'ineq'¶: The type of function for inequality constraint.

class FunctionType(value)¶

Bases: StrEnum

An enumeration.

EQ = 'eq'¶

INEQ = 'ineq'¶

NONE = ''¶

OBJ = 'obj'¶

OBS = 'obs'¶

check_grad(x_vect, approximation_mode=ApproximationMode.FINITE_DIFFERENCES, step=1e-06, error_max=1e-08)¶

Check the gradients of the function.

Parameters:

x_vect (ndarray[Any, dtype[Number]]) – The vector at which the function is checked.
approximation_mode (ApproximationMode) –
The approximation mode.

By default it is set to “finite_differences”.
step (float) –
The step for the approximation of the gradients.

By default it is set to 1e-06.
error_max (float) –
The maximum value of the error.

By default it is set to 1e-08.

Raises:

ValueError – Either if the approximation method is unknown, if the shapes of the analytical and approximated Jacobian matrices are inconsistent or if the analytical gradients are wrong.

Return type:

None

evaluate(x_vect)¶

Evaluate the function and store the dimension of the output space.

Parameters:: x_vect (ndarray[Any, dtype[Number]]) – The value of the inputs of the function.
Returns:: The value of the output of the function.
Return type:: ndarray[Any, dtype[Number]] | Number

static filt_0(arr, floor_value=1e-06)¶

Set the non-significant components of a vector to zero.

The component of a vector is non-significant if its absolute value is lower than a threshold.

Parameters:

arr (ndarray[Any, dtype[Number]]) – The original vector.
floor_value (float) –
The threshold.

By default it is set to 1e-06.

Returns:

The original vector whose non-significant components have been set at zero.

Return type:

ndarray[Any, dtype[Number]]

static from_pickle(file_path)¶

Deserialize a function from a file.

Parameters:: file_path (str | Path) – The path to the file containing the function.
Returns:: The function instance.
Return type:: MDOFunction

classmethod generate_input_names(input_dim, input_names=None)¶

Generate the names of the inputs of the function.

Parameters:

input_dim (int) – The dimension of the input space of the function.
input_names (Sequence[str] | None) – The initial names of the inputs of the function. If there is only one name, e.g. ["var"], use this name as a base name and generate the names of the inputs, e.g. ["var!0", "var!1", "var!2"] if the dimension of the input space is equal to 3. If None, use "x" as a base name and generate the names of the inputs, i.e. ["x!0", "x!1", "x!2"].

Returns:

The names of the inputs of the function.

Return type:

Sequence[str]

get_indexed_name(index)¶

Return the name of function component.

Parameters:: index (int) – The index of the function component.
Returns:: The name of the function component.
Return type:: str

static init_from_dict_repr(**attributes)¶

Initialize a new function.

This is typically used for deserialization.

Parameters:: **attributes – The values of the serializable attributes listed in MDOFunction.DICT_REPR_ATTR.
Returns:: A function initialized from the provided data.
Raises:: ValueError – If the name of an argument is not in MDOFunction.DICT_REPR_ATTR.
Return type:: MDOFunction

is_constraint()¶

Check if the function is a constraint.

The type of a constraint function is either ‘eq’ or ‘ineq’.

Returns:: Whether the function is a constraint.
Return type:: bool

offset(value)¶

Add an offset value to the function.

Parameters:: value (ndarray[Any, dtype[Number]] | Number) – The offset value.
Returns:: The offset function.
Return type:: MDOFunction

static rel_err(a_vect, b_vect, error_max)¶

Compute the 2-norm of the difference between two vectors.

Normalize it with the 2-norm of the reference vector if the latter is greater than the maximal error.

Parameters:

a_vect (ndarray[Any, dtype[Number]]) – A first vector.
b_vect (ndarray[Any, dtype[Number]]) – A second vector, used as a reference.
error_max (float) – The maximum value of the error.

Returns:

The difference between two vectors, normalized if required.

Return type:

float

set_pt_from_database(database, design_space, normalize=False, jac=True, x_tolerance=1e-10)¶

Set the original function and Jacobian function from a database.

For a given input vector, the method MDOFunction.func() will return either the output vector stored in the database if the input vector is present or None. The same for the method MDOFunction.jac().

Parameters:

database (Database) – The database to read.
design_space (DesignSpace) – The design space used for normalization.
normalize (bool) –
If True, the values of the inputs are unnormalized before call.

By default it is set to False.
jac (bool) –
If True, a Jacobian pointer is also generated.

By default it is set to True.
x_tolerance (float) –
The tolerance on the distance between inputs.

By default it is set to 1e-10.

Return type:

None

to_dict()¶

Create a dictionary representation of the function.

This is used for serialization. The pointers to the functions are removed.

Returns:: Some attributes of the function indexed by their names. See MDOFunction.DICT_REPR_ATTR.
Return type:: dict[str, str | int | list[str]]

to_pickle(file_path)¶

Serialize the function and store it in a file.

Parameters:: file_path (str | Path) – The path to the file to store the function.
Return type:: None

COEFF_FORMAT_1D: str = '{:.2e}'¶: The format to be applied to a number when represented in a vector.

COEFF_FORMAT_ND: str = '{: .2e}'¶: The format to be applied to a number when represented in a matrix.

DEFAULT_BASE_INPUT_NAME: str = 'x'¶: The default base name for the inputs.

DICT_REPR_ATTR: list[str] = ['name', 'f_type', 'expr', 'input_names', 'dim', 'special_repr']¶: The names of the attributes to be serialized.

INDEX_PREFIX: str = '!'¶: The character used to separate a name base and a prefix, e.g. "x!1.

MAXIMIZE: ClassVar[bool] = True¶

activate_counters: ClassVar[bool] = True¶: Whether to count the number of function evaluations.

algo_distribution: MLRegressorDistribution¶: The distribution of a machine learning algorithm assessor.

property default_repr: str¶: The default string representation of the function.

property dim: int¶: The dimension of the output space of the function.

property expects_normalized_inputs: bool¶: Whether the functions expect normalized inputs or not.

property expr: str¶: The expression of the function, e.g. “2*x”.

force_real: bool¶: Whether to cast the results to real value.

property func: Callable[[ndarray[Any, dtype[Number]]], ndarray[Any, dtype[Number]] | Number]¶: The function to be evaluated from a given input vector.

has_default_name: bool¶: Whether the name has been set with a default value.

property has_jac: bool¶

Check if the function has an implemented Jacobian function.

Returns:: Whether the function has an implemented Jacobian function.

property input_names: list[str]¶

The names of the inputs of the function.

Use a copy of the original names.

property jac: Callable[[ndarray[Any, dtype[Number]]], ndarray[Any, dtype[Number]]]¶: The Jacobian function to be evaluated from a given input vector.

last_eval: OutputType | None¶

The value of the function output at the last evaluation.

None if it has not yet been evaluated.

property n_calls: int¶

The number of times the function has been evaluated.

This count is both multiprocess- and multithread-safe, thanks to the locking process used by MDOFunction.evaluate().

property name: str¶: The name of the function.

property original_name: str¶: The original name of the function.

property output_names: list[str]¶

The names of the outputs of the function.

Use a copy of the original names.

output_range: float¶: The output range.

special_repr: str¶: The string representation of the function overloading its default string ones.

class gemseo_mlearning.adaptive.criterion.MLDataAcquisitionCriterionFactory[source]¶

Bases: BaseFactory

A factory of MLDataAcquisitionCriterion.

Return type:: BaseFactory

create(class_name, **options)¶

Return an instance of a class.

Parameters:

class_name (str) – The name of the class.
**options (Any) – The arguments to be passed to the class constructor.

Returns:

The instance of the class.

Raises:

TypeError – If the class cannot be instantiated.

Return type:

Any

get_class(name)¶

Return a class from its name.

Parameters:: name (str) – The name of the class.
Returns:: The class.
Raises:: ImportError – If the class is not available.
Return type:: type

get_default_option_values(name)¶

Return the constructor kwargs default values of a class.

Parameters:: name (str) – The name of the class.
Returns:: The mapping from the argument names to their default values.
Return type:: dict[str, str | int | float | bool]

get_default_sub_option_values(name, **options)¶

Return the default values of the sub options of a class.

Parameters:

name (str) – The name of the class.
**options (str) – The options to be passed to the class required to deduce the sub options.

Returns:

The JSON grammar.

Return type:

JSONGrammar

get_library_name(name)¶

Return the name of the library related to the name of a class.

Parameters:: name (str) – The name of the class.
Returns:: The name of the library.
Return type:: str

get_options_doc(name)¶

Return the constructor documentation of a class.

Parameters:: name (str) – The name of the class.
Returns:: The mapping from the argument names to their documentation.
Return type:: dict[str, str]

get_options_grammar(name, write_schema=False, schema_path=None)¶

Return the options JSON grammar for a class.

Attempt to generate a JSONGrammar from the arguments of the __init__ method of the class.

Parameters:

name (str) – The name of the class.
write_schema (bool) –
If True, write the JSON schema to a file.

By default it is set to False.
schema_path (str | None) – The path to the JSON schema file. If None, the file is saved in the current directory in a file named after the name of the class.

Returns:

The JSON grammar.

Return type:

JSONGrammar

get_sub_options_grammar(name, **options)¶

Return the JSONGrammar of the sub options of a class.

Parameters:

name (str) – The name of the class.
**options (str) – The options to be passed to the class required to deduce the sub options.

Returns:

The JSON grammar.

Return type:

JSONGrammar

is_available(name)¶

Return whether a class can be instantiated.

Parameters:: name (str) – The name of the class.
Returns:: Whether the class can be instantiated.
Return type:: bool

update()¶

Search for the classes that can be instantiated.

The search is done in the following order:

The fully qualified module names
The plugin packages
The packages from the environment variables

Return type:: None

PLUGIN_ENTRY_POINT: ClassVar[str] = 'gemseo_plugins'¶: The name of the setuptools entry point for declaring plugins.

property available_criteria: list[str]¶: The names of the available criteria.

property class_names: list[str]¶: The sorted names of the available classes.

failed_imports: dict[str, str]¶: The class names bound to the import errors.