SimulationDatabase Classes for ParMOO’s Multiobjective Database

When defining your MOOP object as described in the name key section, ParMOO will instantiate an internal database for storing multiobjective simulation, function, and constraint information. This information is accessible via various methods of the MOOP class, or from the MOOP.database attribute.

In the future, the type of database will be made a configurable parameter of the MOOP definition.

For now, the abstract base class is accessible via the databases.simulation_database.SimulationDatabase ABC, and the only implementation of this class is the databases.NumpyDatabase class.

from parmoo.databases.simulation_database import SimulationDatabase
from parmoo.databases import NumpyDatabase

SimulationDatabase (ABC)

Abstract base class (ABC) for ParMOO’s SimulationDatabase structure.

class databases.simulation_database.SimulationDatabase(hyperparams)

ABC database specialized for multiobjective simulation data.

Class contains the following adders/getters:

SimulationDatabase.addDesign(*args)
SimulationDatabase.addSimulation(*args)
SimulationDatabase.addObjective(*args)
SimulationDatabase.addConstraint(*args)
SimulationDatabase.getDesignType()
SimulationDatabase.getSimulationType()
SimulationDatabase.getObjectiveType()
SimulationDatabase.getConstraintType()
SimulationDatabase.startDatabase()
SimulationDatabase.checkSimDb(x, sim_name)
SimulationDatabase.checkObjDb(x)
SimulationDatabase.updateSimDb(x, sx, sim_name)
SimulationDatabase.updateObjDb(x, fx, cx)
SimulationDatabase.isEmpty()
SimulationDatabase.browseCompleteSimulations()
SimulationDatabase.getPF(format='ndarray')
SimulationDatabase.getSimulationData(format='ndarray')
SimulationDatabase.getNewSimulationData()
SimulationDatabase.getObjectiveData(format='ndarray')
SimulationDatabase.setCheckpoint(checkpoint, filename="parmoo")
SimulationDatabase.checkpointSimData(x, sx, sim_name, filename)
SimulationDatabase.checkpointObjData(x, fx, cx, filename)
SimulationDatabase.loadCheckpoint(filename="parmoo")

__init__(hyperparams)

Initializer for the SimulationDatabase class.

Parameters:: hyperparams (dict) – Any parameters for configuring the database.

abstract addDesign(name, dtype, tolerance)

Add a new design variable to the SimulationDatabase schema.

Parameters:

name (str, optional) – The unique name of this design variable.
dtype (str) – The string-representation for the numpy dtype for this design variable.
tolerance (float) – The tolerance up to which two different values for this design variables should be considered as “the same.” If a zero is given, then only exact equality is checked.

abstract addSimulation(name, m)

Add new simulations to the SimulationDatabase schema.

Parameters:

name (str) – The unique name of this simulation output.
m (int) – The number of outputs for this simulation.

abstract addObjective(name)

Add a new objective to the SimulationDatabase schema.

Parameters:: name (str) – The unique name of this objective output.

abstract addConstraint(name)

Add a new constraint to the SimulationDatabase schema.

Parameters:: name (str, optional) – The unique name of this constraint violation.

abstract getDesignType()

Get the numpy dtype of all design points for this MOOP.

Returns:: The numpy dtype of this MOOP’s design points. If no design variables have yet been added, returns None.
Return type:: dtype

abstract getSimulationType()

Get the numpy dtypes of the simulation outputs for this MOOP.

Returns:: The numpy dtype of this MOOP’s simulation outputs. If no simulations have been given, returns None.
Return type:: dtype

abstract getObjectiveType()

Get the numpy dtype of an objective point for this MOOP.

Returns:: The numpy dtype of this MOOP’s objective points. If no objectives have yet been added, returns None.
Return type:: dtype

abstract getConstraintType()

Get the numpy dtype of the constraint violations for this MOOP.

Returns:: The numpy dtype of this MOOP’s constraint violation outputs. If no constraint functions have been given, returns None.
Return type:: dtype

abstract startDatabase(): Initialize the SimulationDatabase.

abstract checkSimDb(x, sim_name)

Check self.sim_db[sim_name] to see if the design x was evaluated.

Parameters:

x (dict) – A Python dictionary specifying the keys/names and corresponding values of a design point to search for.
sim_name (str) – The name of the simulation whose database will be searched.

Returns:

returns None if x is not in the database for simulation “sim_name” (up to the design tolerance). Otherwise, returns the corresponding value of sx.

Return type:

None or numpy.ndarray

abstract checkObjDb(x)

Check self.obj_db to see if the design x was evaluated.

Parameters:: x (dict) – A Python dictionary specifying the keys/names and corresponding values of a design point to search for.
Returns:: returns None if x is not in the database (up to the design tolerance). Otherwise, returns the corresponding value of (fx, cx) where fx is the vector-valued objective and cx is the vector-valued constraint violation at x.
Return type:: None or pair of numpy.ndarrays

abstract updateSimDb(x, sx, sim_name)

Update sim_db[sim_name] by adding a design/simulation output pair.

Parameters:

x (dict) – A Python dictionary specifying the keys/names and corresponding values of a design point to add.
sx (ndarray) – A 1D array containing the corresponding simulation output(s).
sim_name (str) – The name of the simulation to whose database the pair (x, sx) will be added into.

abstract updateObjDb(x, fx, cx)

Update the internal objective database with a true evaluation of x.

Parameters:

x (dict) – A Python dictionary containing the value of the design variable to add to ParMOO’s database.
fx (numpy.ndarray) – An array of objective values to add.
cx (numpy.ndarray) – An array of constraint values to add.

abstract isEmpty()

Check whether the database is completely empty.

Returns:: True if and only if every simulation database and the objective database is completely empty (size 0).
Return type:: bool

abstract browseCompleteSimulations()

Browse all design values that are present in every sim database.

Yields:: A sequence of tuples (x, sx) where each x is a (dict) design point that is present in every internal simulation database, and sx is a dictionary of simulation outputs from each of these database.

abstract getPF(format='ndarray')

Extract nondominated and efficient sets from internal databases.

Parameters:: format (str, optional) – Either ‘ndarray’ (default) or ‘pandas’, in order to produce output as a numpy structured array or pandas dataframe. Note: format=’pandas’ is only valid for named inputs.
Returns:: Either a structured array or dataframe (depending on the option selected above) whose column/key names match the names of the design variables, objectives, and constraints. It contains a discrete approximation of the Pareto front and efficient set.
Return type:: numpy structured array or pandas DataFrame

abstract getSimulationData(format='ndarray')

Extract all computed simulation outputs from the MOOP’s database.

Parameters:: format (str, optional) – Either ‘ndarray’ (default) or ‘pandas’, in order to produce output as a numpy structured array or pandas dataframe. Note: format=’pandas’ is only valid for named inputs.
Returns:: A Python dictionary whose keys match the names of the simulations. Each value is either a numpy structured array or pandas dataframe (depending on the option selected above) whose column/key names match the names of the design variables plus either and ‘out’ field for single-output simulations, or ‘out_1’, ‘out_2’, … for multi-output simulations.
Return type:: dict

abstract getNewSimulationData()

Extract simulation outputs that have not yet been viewed.

Returns:: A Python dictionary whose keys match the names of the simulations and whose values are the new data for each variable/simulation output.
Return type:: dict

abstract getObjectiveData(format='ndarray')

Extract all computed objective scores from this database.

Parameters:: format (str, optional) – Either ‘ndarray’ (default) or ‘pandas’, in order to produce output as a numpy structured array or pandas dataframe. Note: format=’pandas’ is only valid for named inputs.
Returns:: Either a structured array or dataframe (depending on the option selected above) whose column/key names match the names of the design variables, objectives, and constraints. It contains the results for every fully evaluated design point.
Return type:: numpy structured array or pandas DataFrame

abstract setCheckpoint(checkpoint, filename='parmoo')

Activate checkpointing.

Parameters:

checkpoint (bool) – Turn checkpointing on (True) or off (False).
filename (str, optional) – Set the base checkpoint filename/path. The checkpoint file will have the JSON format and the extension “.simdb.json” appended to the end of filename.

abstract checkpointSimData(x, sx, sim_name, filename='parmoo')

Append the given simulation data point to the checkpoint file.

Parameters:

x (dict or numpy structured element) – The design value to append.
sx (dict or numpy structured element) – The simulation output to append.
sim_name (str) – The simulation name/index to append to.
filename (str, optional) – The filepath to the checkpointing file(s). Do not include file extensions, they will be appended automatically. Defaults to the value “parmoo” (filename will be “parmoo.simdb.json”).

abstract checkpointObjData(x, fx, cx, filename='parmoo')

Append the given objective data point to the checkpoint file.

Parameters:

x (dict or numpy structured element) – The design value to append.
fx (dict or numpy structured element) – The objective values to append.
cx (dict or numpy structured element) – The constraint violations to append.
filename (str, optional) – The filepath to the checkpointing file(s). Do not include file extensions, they will be appended automatically. Defaults to the value “parmoo” (filename will be “parmoo.simdb.json”).

abstract loadCheckpoint(filename='parmoo')

Reload from the given checkpoint file.

Parameters:: filename (str, optional) – The filepath to the checkpointing file(s). Do not include file extensions, they will be appended automatically. Defaults to the value “parmoo” (filename will be “parmoo.simdb.json”).

NumpyDatabase (default implementation)

Contains the NumpyDatabase class for storing simulation results.

parmoo.NumpyDatabase is the base class for storing multiobjective simulation outputs. Each NumpyDatabase object may contain several simulations, and their corresponding objective and constraint violation scores.

class databases.numpy_database.NumpyDatabase(hyperparams)

A Database class specialized for multiobjective data.

To define the NumpyDatabase, add each design variable, simulation, objective, and constraint by using the following functions:

NumpyDatabase.addDesign(*args)

NumpyDatabase.addSimulation(*args)

NumpyDatabase.addObjective(*args)

NumpyDatabase.addConstraint(*args)

After creating a NumpyDatabase, the following methods may be useful for getting the numpy.dtype of the input/output arrays:

NumpyDatabase.getDesignType()

NumpyDatabase.getSimulationType()

NumpyDatabase.getObjectiveType()

NumpyDatabase.getConstraintType()

To check or add to the simulation database, use:

NumpyDatabase.checkSimDb(x, sim_name)
NumpyDatabase.updateSimDb(x, sx, sim_name)

To check or add to the objective database, use:

NumpyDatabase.checkObjDb(x)
NumpyDatabase.updateObjDb(x, fx, cx)

Finally, the following methods are used to retrieve (filtered) simulation and objective data:

NumpyDatabase.isEmpty()

NumpyDatabase.browseCompleteSimulations()

NumpyDatabase.getPF(format='ndarray')

NumpyDatabase.getSimulationData(format='ndarray')

NumpyDatabase.getNewSimulationData()

NumpyDatabase.getObjectiveData(format='ndarray')

To activate checkpointing, use:

NumpyDatabase.setCheckpoint(checkpoint, filename="parmoo")

Then to force a save or load of the current state, use:

NumpyDatabase.checkpointSimData(x, sx, sim_name, filename="parmoo")
NumpyDatabase.checkpointObjData(x, fx, cx, filename="parmoo")
NumpyDatabase.loadCheckpoint(filename="parmoo")

__init__(hyperparams)

Initializer for the NumpyDatabase class.

Parameters:: hyperparams (dict) – Any parameters for configuring the database.

addDesign(name, dtype, tolerance)

Add a new design variable to the NumpyDatabase schema.

Parameters:

name (str) – The unique name of this design variable.
dtype (str) – The string-representation for the numpy dtype for this design variable.
tolerance (float) – The tolerance up to which two different values for this design variables should be considered as “the same.” If a zero is given, then only exact equality is checked.

addSimulation(name, m)

Add new simulations to the NumpyDatabase schema.

Parameters:

name (str) – The unique name of this simulation output.
m (int) – The number of outputs for this simulation.

addObjective(name)

Add a new objective to the NumpyDatabase schema.

Parameters:: name (str) – The unique name of this objective output.

addConstraint(name)

Add a new constraint to the NumpyDatabase schema.

Parameters:: name (str, optional) – The unique name of this constraint violation.

getDesignType()

Get the numpy dtype of all design points for this MOOP.

Returns:: The numpy dtype of this MOOP’s design points. If no design variables have yet been added, returns None.
Return type:: dtype

getSimulationType()

Get the numpy dtypes of the simulation outputs for this MOOP.

Returns:: The numpy dtype of this MOOP’s simulation outputs. If no simulations have been given, returns None.
Return type:: dtype

getObjectiveType()

Get the numpy dtype of an objective point for this MOOP.

Returns:: The numpy dtype of this MOOP’s objective points. If no objectives have yet been added, returns None.
Return type:: dtype

getConstraintType()

Get the numpy dtype of the constraint violations for this MOOP.

Returns:: The numpy dtype of this MOOP’s constraint violation outputs. If no constraint functions have been given, returns None.
Return type:: dtype

startDatabase(): Initialize the NumpyDatabase.

checkSimDb(x, sim_name)

Check self.sim_db[sim_name] to see if the design x was evaluated.

Parameters:

x (dict) – A Python dictionary specifying the keys/names and corresponding values of a design point to search for.
sim_name (str) – The name of the simulation whose database will be searched.

Returns:

returns None if x is not in the database for simulation “sim_name” (up to the design tolerance). Otherwise, returns the corresponding value of sx.

Return type:

None or numpy.ndarray

checkObjDb(x)

Check self.obj_db to see if the design x was evaluated.

Parameters:: x (dict) – A Python dictionary specifying the keys/names and corresponding values of a design point to search for.
Returns:: returns None if x is not in the database (up to the design tolerance). Otherwise, returns the corresponding value of (fx, cx) where fx is the vector-valued objective and cx is the vector-valued constraint violation at x.
Return type:: None or pair of numpy.ndarrays

updateSimDb(x, sx, sim_name)

Update sim_db[sim_name] by adding a design/simulation output pair.

Parameters:

x (dict) – A Python dictionary specifying the keys/names and corresponding values of a design point to add.
sx (ndarray or list) – A 1D array containing the corresponding simulation output(s).
sim_name (str) – The name of the simulation to whose database the pair (x, sx) will be added into.

updateObjDb(x, fx, cx)

Update the internal objective database with a true evaluation of x.

Parameters:

x (dict) – A dictionary containing the value of the design variable to add to ParMOO’s database.
fx (dict) – A dictionary containing the values of the corresponding objective scores to add to ParMOO’s database.
cx (dict) – A dictionary containing the values of the corresponding constraint violations to add to ParMOO’s database.

isEmpty()

Check whether the database is completely empty.

Returns:: True if and only if every simulation database and the objective database is completely empty (size 0).
Return type:: bool

browseCompleteSimulations()

Browse all design values that are present in every sim database.

Yields:: A sequence of tuples (x, sx) where each x is a (dict) design point that is present in every internal simulation database, and sx is a dictionary of simulation outputs from each of these database.

getPF(format='ndarray')

Extract nondominated and efficient sets from internal databases.

Parameters:: format (str, optional) – Either ‘ndarray’ (default) or ‘pandas’, in order to produce output as a numpy structured array or pandas dataframe. Note: format=’pandas’ is only valid for named inputs.
Returns:: Either a structured array or dataframe (depending on the option selected above) whose column/key names match the names of the design variables, objectives, and constraints. It contains a discrete approximation of the Pareto front and efficient set.
Return type:: numpy structured array or pandas DataFrame

getSimulationData(format='ndarray')

Extract all computed simulation outputs from the MOOP’s database.

Parameters:: format (str, optional) – Either ‘ndarray’ (default) or ‘pandas’, in order to produce output as a numpy structured array or pandas dataframe. Note: format=’pandas’ is only valid for named inputs.
Returns:: A Python dictionary whose keys match the names of the simulations. Each value is either a numpy structured array or pandas dataframe (depending on the option selected above) whose column/key names match the names of the design variables plus either and ‘out’ field for single-output simulations, or ‘out_1’, ‘out_2’, … for multi-output simulations.
Return type:: dict

getNewSimulationData()

Extract simulation outputs that have not yet been viewed.

Returns:: A Python dictionary whose keys match the names of the simulations and whose values are the new data for each variable/simulation output.
Return type:: dict

getObjectiveData(format='ndarray')

Extract all computed objective scores from this MOOP’s database.

Parameters:: format (str, optional) – Either ‘ndarray’ (default) or ‘pandas’, in order to produce output as a numpy structured array or pandas dataframe. Note: format=’pandas’ is only valid for named inputs.
Returns:: Either a structured array or dataframe (depending on the option selected above) whose column/key names match the names of the design variables, objectives, and constraints. It contains the results for every fully evaluated design point.
Return type:: numpy structured array or pandas DataFrame

setCheckpoint(checkpoint, filename='parmoo')

Activate checkpointing.

Parameters:

checkpoint (bool) – Turn checkpointing on (True) or off (False).
filename (str, optional) – Set the base checkpoint filename/path. The checkpoint file will have the JSON format and the extension “.simdb.json” appended to the end of filename.

checkpointSimData(x, sx, sim_name, filename='parmoo')

Append the given simulation data point to the checkpoint file.

Parameters:

x (dict or numpy structured element) – The design value to append.
sx (list or numpy array) – The simulation output to append.
sim_name (str) – The simulation name/index to append to.
filename (str, optional) – The filepath to the checkpointing file(s). Do not include file extensions, they will be appended automatically. Defaults to the value “parmoo” (filename will be “parmoo.simdb.json”).

checkpointObjData(x, fx, cx, filename='parmoo')

Append the given objective data point to the checkpoint file.

Parameters:

x (dict or numpy structured element) – The design value to append.
fx (dict or numpy structured element) – The objective values to append.
cx (dict or numpy structured element) – The constraint violations to append.
filename (str, optional) – The filepath to the checkpointing file(s). Do not include file extensions, they will be appended automatically. Defaults to the value “parmoo” (filename will be “parmoo.simdb.json”).

loadCheckpoint(filename='parmoo')

Reload from the given checkpoint file.

Parameters:: filename (str, optional) – The filepath to the checkpointing file(s). Do not include file extensions, they will be appended automatically. Defaults to the value “parmoo” (filename will be “parmoo.simdb.json”).