History

Suppose we have an optimization problem with one DV group xvars, one constraint con, and the objective is called obj. In this case, the history file would have the following layout:

├── metadata
│   ├── optName
│   ├── optOptions
│   ├── nprocs
│   ├── startTime
│   ├── endTime
│   ├── optTime
│   ├── optimizer
│   ├── version
│   └── optVersion
├── optProb
├── varInfo
│   └── xvars
│       ├── lower
│       ├── upper
│       └── scale
├── conInfo
│   └── con
│       ├── lower
│       ├── upper
│       └── scale
├── objInfo
│   └── obj
│       └── scale
├── 0
│   ├── xuser
│   │   └── xvars
│   ├── funcs
│   │   ├── obj
│   │   └── con
│   ├── iter
│   ├── fail
│   ├── isMajor
|   └── time
├── 1
│   ├── xuser
│   │   └── xvars
│   ├── funcsSens
│   │   ├── obj
│   │   │   └── xvars
│   │   └── con
│   │       └── xvars
│   ├── iter
│   ├── fail
│   ├── isMajor
|   └── time
└── last

The main optimization history is indexed via call counters, in this example 0 and 1. Note that they do not match the major/minor iterations of a given optimizer, since gradient evaluations are stored separate from the function evaluation.

For SNOPT, a number of other values can be requested and stored in each major iteration, such as the feasibility and optimality from the SNOPT print out file.

API

class pyoptsparse.pyOpt_history.History(fileName, optProb=None, temp=False, flag='r')[source]

This class is essentially a thin wrapper around a SqliteDict dictionary to facilitate operations with pyOptSparse

Parameters:

fileNamestr: File name for history file
optProbpyOpt_Optimization: The optimization object
tempbool: Flag to signify that the file should be deleted after it is closed
flagstr: String specifying the mode. Similar to what was used in shelve. n for a new database and r to read an existing one.

close()[source]: Close the underlying database. This should only be used in write mode. In read mode, we close the db during initialization.

getCallCounters()[source]

Returns a list of all call counters stored in the history file.

Returns:

list: a list of strings, each entry being a call counter.

getConInfo(key=None)[source]

Returns the ConInfo, for all keys by default. A key parameter can also be supplied, to retrieve ConInfo corresponding to specific constraints.

Parameters:

keystr or list of str, optional: Specifies for which constraint to extract ConInfo.

Returns:

dict: A dictionary containing ConInfo. For a single key, the return is one level deeper.

getConNames()[source]

Returns the names of constraints.

Returns:

list of str: A list containing the names of constraints.

getDVInfo(key=None)[source]

Returns the DVInfo, for all keys by default. A key parameter can also be supplied, to retrieve DVInfo corresponding to specific DVs.

Parameters:

keystr or list of str, optional: Specifies for which DV to extract DVInfo.

Returns:

dict: A dictionary containing DVInfo. For a single key, the return is one level deeper.

getDVNames()[source]

Returns the names of the DVs.

Returns:

list of str: A list containing the names of DVs.

getExtraFuncsNames()[source]

Returns extra funcs names. These are extra key: value pairs stored in the funcs dictionary for each iteration, which are not used by the optimizer.

Returns:

list of str: A list containing the names of extra funcs keys.

getIterKeys()[source]

Returns the keys available at each optimization iteration. This function is useful for inspecting the history file, to determine what information is saved at each iteration.

Returns:

list of str: A list containing the names of keys stored at each optimization iteration.

getMetadata()[source]

Returns a copy of the metadata stored in the history file.

Returns:

dict: A dictionary containing the metadata.

getObjInfo(key=None)[source]

Returns the ObjInfo, for all keys by default. A key parameter can also be supplied, to retrieve ObjInfo corresponding to specific keys.

Parameters:

keystr or list of str, optional: Specifies for which obj to extract ObjInfo.

Returns:

dict: A dictionary containing ObjInfo. For a single key, the return is one level deeper.

Notes

Recall that for the sake of generality, pyOptSparse allows for multiple objectives to be added. This feature is not used currently, but does make ObjInfo follow the same structure as ConInfo and DVInfo. Because of this, it is recommended that this function be accessed using the optional key argument.

getObjNames()[source]

Returns the names of the objectives.

Returns:

list of str: A list containing the names of objectives.

Notes

Recall that for the sake of generality, pyOptSparse allows for multiple objectives to be added. This feature is not used currently, but does make ObjNames follow the same structure as ConNames and DVNames.

getOptProb()[source]

Returns a copy of the optProb associated with the optimization.

Returns:

optProbpyOpt_optimization object: The optProb associated with the optimization. This is taken from the history file, and therefore has the comm and objFun fields removed.

getValues(names=None, callCounters=None, major=True, scale=False, stack=False, allowSens=False)[source]

Parses an existing history file and returns a data dictionary used to post-process optimization results, containing the requested optimization iteration history.

Parameters:

nameslist or str: the values of interest, can be the name of any DV, objective or constraint, or a list of them. If None, all values are returned. This includes the DVs, funcs, and any values stored by the optimizer.
callCounterslist of ints, can also contain ‘last’: a list of callCounters to extract information from. If the callCounter is invalid, i.e. outside the range or is a funcsSens evaluation, then it is skipped. ‘last’ represents the last major iteration. If None, values from all callCounters are returned.
majorbool: flag to specify whether to include only major iterations.
scalebool: flag to specify whether to apply scaling for the values. True means to return values that are scaled the same way as the actual optimization.
stackbool: flag to specify whether the DV should be stacked into a single numpy array with the key xuser, or retain their separate DVGroups.
allowSens: bool: flag to specify whether gradient evaluation iterations are allowed. If true, it is up to the user to ensure that the callCounters specified contain the information requested.

Returns:

dict: a dictionary containing the information requested. The keys of the dictionary correspond to the names requested. Each value is a numpy array with the first dimension equal to the number of callCounters requested.

Notes

Regardless of the major flag, failed function evaluations are not returned.

Examples

First we can request DV history over all major iterations:

>>> hist.getValues(names='xvars', major=True)
{'xvars': array([[-2.00000000e+00,  1.00000000e+00],
    [-1.00000000e+00,  9.00000000e-01],
    [-5.00305827e-17,  4.21052632e-01],
    [ 1.73666171e-06,  4.21049838e-01],
    [ 9.08477459e-06,  4.21045261e-01],
    [ 5.00000000e-01,  2.84786405e-01],
    [ 5.00000000e-01,  5.57279939e-01],
    [ 5.00000000e-01,  2.00000000e+00]])}

Next we can look at DV and optimality for the first and last iteration only:

>>> hist.getValues(names=['xvars','optimality'],callCounters=[0,'last'])
{'optimality': array([1.27895528, 0. ]),
'xvars': array([[-2. , 1. ],
                [ 0.5, 2. ]])}

pointExists(callCounter)[source]

Determine if callCounter is in the database

Parameters:

callCounterint or str of int

Returns:

bool: True if the callCounter exists in the history file. False otherwise.

read(key)[source]

Read data for an arbitrary key. Returns None if key is not found. If passing in a callCounter, it should be verified by calling pointExists() first.

Parameters:

keystr or int: generic key[str] or callCounter[int]

Returns:

dict: The value corresponding to key is returned. If the key is not found, None is returned instead.

write(callCounter, data)[source]

This is the main to write data. Basically, we just pass in the callCounter, the integer forming the key, and a dictionary which will be written to the key

Parameters:

callCounterint: the callCounter to write to
datadict: the dictionary corresponding to the callCounter

writeData(key, data)[source]

Write arbitrary key:data value to db.

Parameters:

keystr: The key to be added to the history file
data: The data corresponding to the key. It can be anything as long as it is serializable in sqlitedict.