11.2. da.p7core

pSeven Core package.

Modules

da.p7core.blackbox pSeven Core blackbox module.
da.p7core.gtapprox Generic Tool for Approximation (GTApprox) module.
da.p7core.gtdf Generic Tool for Data Fusion (GTDF) module.
da.p7core.gtdoe Generic Tool for Design of Experiments (GTDoE) module.
da.p7core.gtdr Generic Tool for Dimension Reduction (GTDR) module.
da.p7core.gtopt Generic Tool for Optimization (GTOpt) module.
da.p7core.gtsda Generic Tool for Sensitivity and Dependency Analysis (GTSDA) module.
da.p7core.loggers Log levels and default logger.
da.p7core.stat Statistical utilities module.
da.p7core.status Status constants.
da.p7core.watchers Default watcher.

Classes

da.p7core.License(obj, parent[, api]) License information interface.
da.p7core.Options(obj, parent_impl) General options interface.
da.p7core.Result(status, info, solutions, fields) General result.

Exceptions

da.p7core.BBPrepareException(*args) Blackbox initialization error.
da.p7core.Exception Base pSeven Core exception.
da.p7core.FeatureNotAvailableError Particular feature not supported.
da.p7core.GTException Base pSeven Core Generic Tools exception class.
da.p7core.IllegalStateError Attempt to perform action on object with unsuitable state.
da.p7core.InapplicableTechniqueException The approximation technique requested is incompatible with the learning dataset and/or options given.
da.p7core.InfeasibleProblemError No feasible points found.
da.p7core.InternalError Internal error.
da.p7core.InvalidOptionNameError Wrong option name has been passed.
da.p7core.InvalidOptionsError Wrong option has been passed.
da.p7core.InvalidOptionValueError Wrong option value has been passed.
da.p7core.InvalidProblemError Invalid/inconsistent problem.
da.p7core.LicenseError Required license feature not found, or other license error.
da.p7core.LoggerException(*args) Internal logger error.
da.p7core.NanInfError Too many NaN/Inf values encountered.
da.p7core.OutOfMemoryError The problem given is too big to be solved.
da.p7core.UnsupportedProblemError Given problem can not be solved by current version of optimizer.
da.p7core.UserEvaluateException(*args) Blackbox evaluation error.
da.p7core.UserTerminated Process terminated by user.
da.p7core.WatcherException(*args) Internal watcher error.
da.p7core.WrongUsageError Invalid usage of model API.
da.p7core.XTException Base pSeven Core Extras exception.

11.2.1. License — license information

da.p7core.License(obj, parent[, api]) License information interface.
da.p7core.License.features() Get information on captured license features.
class da.p7core.License(obj, parent, api=<da.p7core.license._API object>)

License information interface.

This class only provides license information methods to other classes and should never be instantiated by user.

features()

Get information on captured license features.

Returns:license feature names and their state
Return type:dict

Returns a dictionary where keys are names of requested license features and values indicate their availability: True if captured and available, False if not.

For feature names and other details, see section License Usage.

11.2.2. Options — options interface

da.p7core.Options(obj, parent_impl) General options interface.
da.p7core.Options.get([name]) Get current value of an option or all options.
da.p7core.Options.info([name]) Get option information.
da.p7core.Options.list All options’ names.
da.p7core.Options.reset() Reset all options to their default values.
da.p7core.Options.set(option[, value]) Set option values.
da.p7core.Options.values Non-default option values.
class da.p7core.Options(obj, parent_impl)

General options interface.

This class only provides option handling methods to other classes and should never be instantiated by user.

get(name=None)

Get current value of an option or all options.

Parameters:name (str) – option name
Returns:current option value
Return type:str or dict

Get the current value of an option as a string.

If name is None, get all current option values as a dictionary where keys are option names; all keys and values are strings.

If an option was not set(), returns its default value.

info(name=None)

Get option information.

Parameters:name (str) – option name
Returns:option summary
Return type:dict

Get a dictionary containing option default, short description, type and allowed values. Example:

>>> builder.options.info('GTApprox/InternalValidation')
{'OptionDescription': {'Default': 'False',
                       'Description': 'Enable or disable internal validation.',
                       'Name': 'GTApprox/InternalValidation',
                       'Type': 'bool',
                       'Values': ['False', 'True']}}

If name is None, get information on all available options as a dictionary where keys are option names (strings) and values are option summaries (dictionaries).

list

All options’ names.

Type:list

List of all valid options’ names.

Example:

>>> from da.p7core import gtdr
>>> builder = gtdr.Builder()
>>> builder.options.list
['GTDR/LogLevel', 'GTDR/MinImprove', 'GTDR/Normalize', 'GTDR/UseProjection']
reset()

Reset all options to their default values.

set(option, value=None)

Set option values.

Parameters:
  • option (str or dict) – option name, or a dictionary of option names and values
  • value (str or None) – new option value (for a single option)

If option type is str, set it to value. If value is omitted or None, the option is reset to its default.

If option type is dict, set option values by dictionary. The value parameter is ignored, and specifying None as value does not reset the options from dictionary. To reset an option using the dictionary form, specify None as the dictionary value — see the example.

Example:

>>> from da.p7core import gtdr
>>> builder = gtdr.Builder()
>>> # The following two lines...
>>> builder.options.set('GTDR/Normalize', "on")  # normalize input
>>> builder.options.set('GTDR/Technique')        # use default technique
>>> # ...are equivalent to this one:
>>> builder.options.set({'GTDR/Normalize': True, 'GTDR/Technique': None})

Note

This method does not validate option values (only some type checks are done). Options are checked when you call the main processing method, for example da.p7core.gtapprox.Builder.build() or da.p7core.gtopt.Solver.solve(). If an invalid option value was specified using set(), these methods throw an InvalidOptionsError exception. Check option descriptions for their valid values.

values

Non-default option values.

Type:dict

A dictionary with option values and option names as keys; all keys and values are strings.

Contains only those options that were set() explicitly.

11.2.3. Result — general result

da.p7core.Result(status, info, solutions, fields) General result.
da.p7core.Result.designs Returns all designs if they are available.
da.p7core.Result.designs_fields Available designs fields.
da.p7core.Result.designs_samples Available designs sample type filters.
da.p7core.Result.feasible([fields]) Returns feasible points from the result if they are available.
da.p7core.Result.infeasible([fields]) Returns infeasible points from result if they are available.
da.p7core.Result.info Result information.
da.p7core.Result.model Internal model trained by the Adaptive Design of Experiments technique.
da.p7core.Result.names Names of variables, objectives, and constraints as they were defined by the problem.
da.p7core.Result.optimal([fields]) Returns optimal points from result if they are available.
da.p7core.Result.pprint([fields, …]) Print formatted result data.
da.p7core.Result.solutions Returns all solutions if they are available.
da.p7core.Result.solutions_fields Available solution fields.
da.p7core.Result.status Result status.
class da.p7core.Result(status, info, solutions, fields, problem=None, diagnostics=None, model=None, designs=None, solutions_subsets=None, finalize=True)

General result.

New in version 6.14.

An object of this class is only returned by build_doe() and by solve() if compatibility is False. This class should never be instantiated by user.

A Result object stores the numerical part of results (values of variables and responses) with some additional information. It can return all results data or filter it by some fields or point types.

designs_fields

Available designs fields.

Type:tuple(list[str], list[str])

Available fields (x, f, c, and so on) and possible subfields like x.x1, f.f1 and other.

designs_samples

Available designs sample type filters.

Type:list[str]

Available subsample filters are divided into two groups:

  • Feasibility and optimality filters — filter designs according to values of constraints and objectives.
    • "feasible" — get points for which all constraint values are known and satisfied (confirmed feasible points), with regard to constraint tolerance.
    • "infeasible" — get points where at least one of the constraints is violated or NaN (confirmed infeasible points).
    • "undefined" — get points that are not confirmed feasible or infeasible — for example, some constraints were not evaluated, but those that were evaluated are not violated.
    • "potentially feasible" — in tasks with deferred constraint evaluations, get points to consider when evaluating the deferred responses — those that will resolve into feasible or infeasible after such evaluations, and are not yet defined until then; this is different from the undefined points — an undefined point will not resolve even if you complete the deferred evaluations.
  • Data source filters — used to include or exclude the designs from the initial sample.
    • "all" — get all designs, new and initial regardless.
    • "initial" — get initial sample points, skip new generated points unless the "new" filter is also specified.
    • "new" — get new generated points only, skip initial sample points unless the "initial" filter is also specified.

You can combine the filters to select only the designs you need. Filters from different groups are applied using “and” logic, for example:

  • ["initial", "feasible"] gets the points that come from the initial sample and are feasible.
  • ["new", "undefined"] gets only the new points where some constraints were not evaluated.

Filters from the same group are applied using “or” logic, for example:

  • ["new", "feasible", "potentially feasible"] gets the new points that are confirmed feasible, or may yet resolve to feasible.
designs(fields=None, sample_type=None)

Get all available problem data, optionally filtered by feasibility and sample type.

Parameters:
  • fields (str or list[str]) – fields to output
  • sample_type (str or list[str]) – the filters to use
Returns:

problem data (default); an empty array if problem history was disabled in solving
Return type:

numpy.ndarray

If problem history was enabled in solving (see GTOpt history, for example), this method provides access to full problem data, including the initial sample, new generated designs, and response values calculated internally by the solver. If problem history was disabled, returns an empty array.

For the available fields, see designs_fields.

For sample type filters, see designs_samples.

You can also get values of any top-level fields ("x", "f", "c" and so on) using the following attributes:

  • evaluations.c (ndarray) — constraint values.
  • evaluations.f (ndarray) — objective values.
  • evaluations.x (ndarray) — values of variables.
feasible(fields=None)

Returns feasible points from the result if they are available.

Parameters:fields (list[str]) – fields to output
Returns:feasible points
Return type:numpy.ndarray

For the available fields, see fields.

fields

Available solution fields.

Type:tuple(list[str], list[str])

Available fields (x, f, c, and so on) and possible subfields like x.x1, f.f1 and other.

infeasible(fields=None)

Returns infeasible points from result if they are available.

Parameters:fields (list[str]) – fields to output
Returns:infeasible points
Return type:numpy.ndarray

For the available fields, see fields.

info

Result information.

Type:dict
model

Internal model trained by the Adaptive Design of Experiments technique.

Type:gtapprox.Model

This attribute is None in GTOpt results and in GTDoE results generated by any GTDoE technique other than the Adaptive Design of Experiments. May also be None in an Adaptive Design of Experiments result, if the internal model never reached the minimum accuracy specified by the GTDoE/Adaptive/InitialModelQualityLevel option.

names

Names of variables, objectives, and constraints as they were defined by the problem. If some names are not available, corresponding attribute is an empty list.

  • names.c (list[str]) — names of constraints.
  • names.f (list[str]) — names of objectives.
  • names.x (list[str]) — names of variables.
optimal(fields=None)

Returns optimal points from result if they are available.

Parameters:fields (None, iterable(str)) – fields to output
Returns:optimal points
Return type:numpy.ndarray
pprint(fields=None, filter_type=None, file=<open file '<stdout>', mode 'w'>, precision=8, designs=False, limit=None)

Print formatted result data.

Parameters:
  • fields (None or list[str]) – fields to output (by default, output all available fields)
  • filter_type (str) – the filter to use
  • precision (int) – floating point value precision
  • designs (bool) – print all available problem data (True) or solutions only (False)
  • file (io.TextIOBase) – output facility
  • designs – print designs if True
  • limit (int) – the maximal number of points to print

Prints the formatted representation of result data to file with the specified precision for floating point values.

By default, prints the solution data only (see solutions()). To print all problem data (see designs()), set designs to True.

Similarly to designs() and solutions(), you can select the fields and subsample types to output using the fields and filter_type parameters. The fields and filters you specify should be consistent with the type of output (all designs or solutions only), set by designs.

solutions(fields=None, filter_type=None)

Get solutions, optionally filtered by feasibility, optimality, and their presence in the initial sample.

Parameters:
  • fields (list[str]) – fields to output
  • filter_type (str or list[str]) – the filters to use
Returns:

solution points
Return type:

numpy.ndarray

For the available fields, see solutions_fields.

Available filters are divided into two groups:

  • Feasibility and optimality filters — filter solutions according to values of constraints and objectives. In optimization, used to sort solutions in the extended result dataset (see Optimal and Infeasible Result Sets).
    • "feasible" — in DoE, get points for which all constraint values are known and satisfied (confirmed feasible points). In optimization, get solutions that satisfy constraints, with regard to constraint tolerance. If the extended result is disabled, "feasible" is the same as "optimal".
    • "infeasible" — in DoE, get points that are known to violate at least one of the constraints (confirmed infeasible points). In optimization, get solutions from the infeasible result dataset (optimal solutions that violate constraints more than constraint tolerance). If the extended result is disabled, there will be no such solutions.
    • "optimal" — in DoE, get points that are feasible and Pareto-optimal with regard to minimization and maximization objectives specified by the @GT/ObjectiveType hint. In optimization, get all solutions: if the extended result is disabled, "optimal" is the same as "feasible".
    • "potentially feasible" — in tasks with deferred constraint evaluations, get points to consider when evaluating the deferred responses to find the feasible points. Potentially feasible points are those that will resolve into feasible or infeasible after such evaluations, and are not yet defined until then.
    • "potentially optimal" — in tasks with deferred responses (objectives, constraints), get points to consider when evaluating the deferred responses to find the Pareto-optimal points. Potentially optimal points will resolve into optimal or suboptimal (dominated) after such evaluations. In tasks with deferred evaluations, the optimal set is always a subset of this one.
  • Data source filters — used to include or exclude the initial sample points.
    • "all" — all points, new and initial regardless.
    • "initial" — get points or solutions that were already found in the initial sample, exclude new ones unless the "new" filter is also specified.
    • "new" — get only points or solutions that were not found in the initial sample unless the "initial" filter is also specified.
    • "auto" — use defaults determined by the technique that generated the result.

You can combine the filters to select only the data you need. Filters from different groups are applied using “and” logic, for example:

  • ["feasible", "new"] — get only points that are feasible and new (not found in the initial sample).

Filters from the same group are applied using “or” logic, for example:

  • ["initial", "new"] — get points that are either new or come from an initial sample (actually the same as "all").
  • ["initial", "new", "feasible"] — get whatever feasible points.

You can also get values of variables, objectives and constraints using the following attributes:

  • solutions.c (ndarray) — constraint values.
  • solutions.f (ndarray) — objective values.
  • solutions.x (ndarray) — values of variables.
solutions_fields

Available solution fields.

Type:tuple(list[str], list[str])

Available fields (x, f, c, and so on) and possible subfields like x.x1, f.f1 and other.

status

Result status.

Type:Status

For details, see section Status.

11.2.4. Exceptions

da.p7core.BBPrepareException(*args) Blackbox initialization error.
da.p7core.Exception Base pSeven Core exception.
da.p7core.FeatureNotAvailableError Particular feature not supported.
da.p7core.GTException Base pSeven Core Generic Tools exception class.
da.p7core.IllegalStateError Attempt to perform action on object with unsuitable state.
da.p7core.InapplicableTechniqueException The approximation technique requested is incompatible with the learning dataset and/or options given.
da.p7core.InfeasibleProblemError No feasible points found.
da.p7core.InternalError Internal error.
da.p7core.InvalidOptionNameError Wrong option name has been passed.
da.p7core.InvalidOptionsError Wrong option has been passed.
da.p7core.InvalidOptionValueError Wrong option value has been passed.
da.p7core.InvalidProblemError Invalid/inconsistent problem.
da.p7core.LicenseError Required license feature not found, or other license error.
da.p7core.LoggerException(*args) Internal logger error.
da.p7core.NanInfError Too many NaN/Inf values encountered.
da.p7core.OutOfMemoryError The problem given is too big to be solved.
da.p7core.UnsupportedProblemError Given problem can not be solved by current version of optimizer.
da.p7core.UserEvaluateException(*args) Blackbox evaluation error.
da.p7core.UserTerminated Process terminated by user.
da.p7core.WatcherException(*args) Internal watcher error.
da.p7core.WrongUsageError Invalid usage of model API.
da.p7core.XTException Base pSeven Core Extras exception.

Inheritance

exception da.p7core.BBPrepareException(*args)

Blackbox initialization error.

exception da.p7core.Exception

Base pSeven Core exception.

exception da.p7core.FeatureNotAvailableError

Particular feature not supported.

exception da.p7core.GTException

Base pSeven Core Generic Tools exception class.

exception da.p7core.IllegalStateError

Attempt to perform action on object with unsuitable state.

exception da.p7core.InapplicableTechniqueException

The approximation technique requested is incompatible with the learning dataset and/or options given.

exception da.p7core.InfeasibleProblemError

No feasible points found.

exception da.p7core.InternalError

Internal error.

exception da.p7core.InvalidOptionNameError

Wrong option name has been passed.

exception da.p7core.InvalidOptionsError

Wrong option has been passed.

exception da.p7core.InvalidOptionValueError

Wrong option value has been passed.

exception da.p7core.InvalidProblemError

Invalid/inconsistent problem.

exception da.p7core.LicenseError

Required license feature not found, or other license error. See section License Usage for details.

exception da.p7core.LoggerException(*args)

Internal logger error.

exception da.p7core.NanInfError

Too many NaN/Inf values encountered.

exception da.p7core.OutOfMemoryError

The problem given is too big to be solved.

exception da.p7core.UnsupportedProblemError

Given problem can not be solved by current version of optimizer.

exception da.p7core.UserEvaluateException(*args)

Blackbox evaluation error.

exception da.p7core.UserTerminated

Process terminated by user.

exception da.p7core.WatcherException(*args)

Internal watcher error.

exception da.p7core.WrongUsageError

Invalid usage of model API.

exception da.p7core.XTException

Base pSeven Core Extras exception.