Optimization¶

class
pyoptsparse.pyOpt_optimization.
Optimization
(name, objFun, comm=None)[source]¶ The main purpose of this class is to describe the structure and potentially, sparsity pattern of an optimization problem.
 Parameters
 namestr
Name given to optimization problem.
 objFunPython function handle
Function handle used to evaluate the objective function.
 commMPI intra communication
The communicator this problem will be solved on. This is required for both analysis when the objective is computed in parallel as well as to use the internal parallel gradient computations. Defaults to MPI.COMM_WORLD if not given.

addConGroup
(name, nCon, lower=None, upper=None, scale=1.0, linear=False, wrt=None, jac=None)[source]¶ Add a group of variables into a variable set. This is the main function used for adding variables to pyOptSparse.
 Parameters
 namestr
Constraint name. All names given to constraints must be unique
 nConint
The number of constraints in this group
 lowerscalar or array
The lower bound(s) for the constraint. If it is a scalar, it is applied to all nCon constraints. If it is an array, the array must be the same length as nCon.
 upperscalar or array
The upper bound(s) for the constraint. If it is a scalar, it is applied to all nCon constraints. If it is an array, the array must be the same length as nCon.
 scalescalar or array
A scaling factor for the constraint. It is generally advisable to have most optimization constraint around the same order of magnitude.
 linearbool
Flag to specify if this constraint is linear. If the constraint is linear, both the ‘wrt’ and ‘jac’ keyword arguments must be given to specify the constant portion of the constraint Jacobian.
 wrtiterable (list, set, OrderedDict, array etc)
‘wrt’ stand for stands for ‘With Respect To’. This specifies for what dvs have nonzero Jacobian values for this set of constraints. The order is not important.
 jacdictionary
For linear and sparse nonlinear constraints, the constraint Jacobian must be passed in. The structure is jac dictionary is as follows:
{‘dvName1’:<matrix1>, ‘dvName2’, <matrix1>, …}
They keys of the Jacobian must correspond to the dvGroups given in the wrt keyword argument. The dimensions of each “chunk” of the constraint Jacobian must be consistent. For example, <matrix1> must have a shape of (nCon, nDvs) where nDVs is the total number of design variables in dvName1. <matrix1> may be a dense numpy array or it may be scipy sparse matrix. However, it is HIGHLY recommended that sparse constraints are supplied to pyOptSparse using the pyOptSparse’s simplified sparse matrix format. The reason for this is that it is impossible for force scipy sparse matrices to keep a fixed sparsity pattern; if the sparsity pattern changes during an optimization, IT WILL FAIL.
The three simplified pyOptSparse sparse matrix formats are summarized below:
mat = {‘coo’:[row, col, data], ‘shape’:[nrow, ncols]} # A coo matrix mat = {‘csr’:[rowp, colind, data], ‘shape’:[nrow, ncols]} # A csr matrix mat = {‘coo’:[colp, rowind, data], ‘shape’:[nrow, ncols]} # A csc matrix
Note that for nonlinear constraints (linear=False), the values themselves in the matrices in jac do not matter, but the sparsity structure does matter. It is imperative that entries that will at some point have nonzero entries have nonzero entries in jac argument. That is, we do not let the sparsity structure of the Jacobian change throughout the optimization. This stipulation is automatically checked internally.

addVar
(name, *args, **kwargs)[source]¶ This is a convenience function. It simply calls addVarGroup() with nVars=1. Variables added with addVar() are returned as scalars.

addVarGroup
(name, nVars, type='c', value=0.0, lower=None, upper=None, scale=1.0, offset=0.0, choices=None, **kwargs)[source]¶ Add a group of variables into a variable set. This is the main function used for adding variables to pyOptSparse.
 Parameters
 namestr
Name of variable group. This name should be unique across all the design variable groups
 nVarsint
Number of design variables in this group.
 typestr.
String representing the type of variable. Suitable values for type are: ‘c’ for continuous variables, ‘i’ for integer values and ‘d’ for discrete selection.
 valuescalar or array.
Starting value for design variables. If it is a a scalar, the same value is applied to all ‘nVars’ variables. Otherwise, it must be iterable object with length equal to ‘nVars’.
 lowerscalar or array.
Lower bound of variables. Scalar/array usage is the same as value keyword
 upperscalar or array.
Upper bound of variables. Scalar/array usage is the same as value keyword
 scalescalar or array. Define a user supplied scaling
variable for the design variable group. This is often necessary when design variables of widely varying magnitudes are used within the same optimization. Scalar/array usage is the same as value keyword.
 offsetscalar or array. Define a user supplied offset
variable for the design variable group. This is often necessary when design variable has a large magnitude, but only changes a little about this value.
 choiceslist
Specify a list of choices for discrete design variables
Notes
Calling addVar() and addVarGroup(…, nVars=1, …) are NOT equivalent! The variable added with addVar() will be returned as scalar, while variable returned from addVarGroup will be an array of length 1.
It is recommended that the addVar() and addVarGroup() calls follow the examples above by including all the keyword arguments. This make it very clear the intent of the script’s author. The type, value, lower, upper and scale should be given for all variables even if the default value is used.
Examples
>>> # Add a single design variable 'alpha' >>> optProb.addVar('alpha', type='c', value=2.0, lower=0.0, upper=10.0, scale=0.1) >>> # Add 10 unscaled variables of 0.5 between 0 and 1 with name 'y' >>> optProb.addVarGroup('y', type='c', value=0.5, lower=0.0, upper=1.0, scale=1.0)

checkConName
(conName)[source]¶ Check if the desired constraint name has already been added. If it is has already been added, return a mangled name (a number appended) that is valid. This is intended to be used by classes that automatically add constraints to pyOptSparse.
 Parameters
 conNamestr
Constraint name to check validity on
 Returns
 validNamestr
A valid constraint name. May be the same as conName it that was, in fact, a valid name.

checkVarName
(varName)[source]¶ Check if the desired variable name varName if has already been added. If it is has already been added, return a mangled name (a number appended) that is valid. This is intended to be used by classes that automatically add variables to pyOptSparse
 Parameters
 varNamestr
Variable name to check validity on
 Returns
 validNamestr
A valid variable name. May be the same as varName it that was, in fact, a valid name.

delVar
(name)[source]¶ Delete a variable or variable group
 Parameters
 namestr
Name of variable or variable group to remove

evaluateLinearConstraints
(x, fcon)[source]¶ This function is required for optimizers that do not explicitly treat the linear constraints. For those optimizers, we will evaluate the linear constraints here. We place the values of the linear constraints in the fcon dictionary such that it appears as if the user evaluated these constraints.
 Parameters
 xarray
This must be the processed xvector from the optimizer
 fcondict
Dictionary of the constraints. The linear constraints are to be added to this dictionary.

finalizeConstraints
()[source]¶ This function should not need to be called by the user
There are several functions for this routine:
Determine the number of constraints
Determine the final scaling array for the design variables
Determine if it is possible to return a complete dense Jacobian. Most of this time, we should be using the dictionary based return

finalizeDesignVariables
()[source]¶ Communicate design variables potentially from different processors and form the DVOffset dict. This routine should be called from the individual optimizers

getDVConIndex
(startIndex=1, printIndex=True)[source]¶ Return the index of a scalar DV/constraint, or the beginning and end index (inclusive) of a DV/constraint array. This is useful for looking at SNOPT gradient check output, and the default startIndex=1 is for that purpose

getDVs
()[source]¶ Return a dictionary of the design variables. In most common usage, this function is not required.
 Returns
 outDVsdict
The dictionary of variables. This is the same as ‘x’ that would be used to call the user objective function.

getOrdering
(conOrder, oneSided, noEquality=False)[source]¶ Internal function that is used to produce a index list that reorders the constraints the way a particular optimizer needs.
 Parameters
 conOrderlist
This must contain the following 4 strings: ‘ni’, ‘li’, ‘ne’, ‘le’ which stand for nonlinear inequality, linear inequality, nonlinear equality and linear equality. This defines the order that the optimizer wants the constraints
 oneSidedbool
Flag to do all constraints as onesided instead of two sided. Most optimizers need this but some can deal with the twosided constraints properly (snopt and ipopt for example)
 noEqualitybool
Flag to split equality constraints into two inequality constraints. Some optimizers (CONMIN for example) can’t do equality constraints explicitly.

printSparsity
(verticalPrint=False)[source]¶ This function prints an (ASCII) visualization of the Jacobian sparsity structure. This helps the user visualize what pyOptSparse has been given and helps ensure it is what the user expected. It is highly recommended this function be called before the start of every optimization to verify the optimization problem setup.
 Parameters
 verticalPrintbool
True if the design variable names in the header should be printed vertically instead of horizontally. If true, this will make the constraint Jacobian print out more narrow and taller.
Warning
This function is collective on the optProb comm. It is therefore necessary to call this function on all processors of the optProb comm.

processConstraintJacobian
(gcon)[source]¶ This generic function is used to assemble the entire constraint Jacobian. The order of the constraint Jacobian is in ‘natural’ ordering, that is the order the constraints have been added (mostly; since it can be different when constraints are added on different processors).
The input is gcon, which is dict or an array. The array format should only be used when the pyOpt_gradient class is used since this results in a dense (and correctly oriented) Jacobian. The user should NEVER return a dense Jacobian since this extremely fickle and easy to break. The dict ‘gcon’ must contain only the nonlinear constraints Jacobians; the linear ones will be added automatically.
 Parameters
 gconarray or dict
Constraint gradients. Either a complete 2D array or a nested dictionary of gradients given with respect to the variables.
 Returns
 gcondict with csr data
Return the Jacobian in a sparse csr format. can be easily converted to csc, coo or dense format as required by individual optimizers
Warning
This function should not need to be called by the user

processContoDict
(fcon_in, scaled=True, dtype='d', natural=False, multipliers=False)[source]¶  Parameters
 fcon_inarray
Array of constraint values to be converted into a dictionary
 scaledbool
Flag specifying if the returned array should be scaled by the pyOpt scaling. The only type this is not true is when the automatic derivatives are used
 dtypestr
String specifying the data type to return. Normally this is ‘d’ for a float. The complexstep derivative computations will call this function with ‘D’ to ensure that the complex perturbations pass through correctly.
 naturalbool
Flag to specify if the input data is in the natural ordering. This is only used when computing gradient automatically with FD/CS.
 multipliersbool
Flag that indicates whether this deprocessing is for the multipliers or the constraint values. In the case of multipliers, no constraint offset should be applied.
Warning
This function should not need to be called by the user

processContoVec
(fcon_in, scaled=True, dtype='d', natural=False)[source]¶  Parameters
 fcon_indict
Dictionary of constraint values
 scaledbool
Flag specifying if the returned array should be scaled by the pyOpt scaling. The only type this is not true is when the automatic derivatives are used
 dtypestr
String specifying the data type to return. Normally this is ‘d’ for a float. The complexstep derivative computations will call this function with ‘D’ to ensure that the complex perturbations pass through correctly.
 naturalbool
Flag to specify if the data should be returned in the natural ordering. This is only used when computing gradient automatically with FD/CS.
Warning
This function should not need to be called by the user

processObjectiveGradient
(funcsSens)[source]¶ This generic function is used to assemble the objective gradient(s)
 Parameters
 funcsSensdict
Dictionary of all function gradients. Just extract the objective(s) we need here.
Warning
This function should not need to be called by the user

processObjtoDict
(fobj_in, scaled=True)[source]¶ This function converts the objective in array form to the corresponding dictionary form.
 Parameters
 fobj_infloat or ndarray
The objective in array format. In the case of a single objective, a float can also be accepted.
 scaledbool
Flag specifying if the returned dictionary should be scaled by the pyOpt scaling.
 Returns
 fobjdictionary
The dictionary form of fobj_in, which is just a key:value pair for each objective.

processObjtoVec
(funcs, scaled=True)[source]¶ This is currently just a stubfunction. It is here since it the future we may have to deal with multiple objectives so this function will deal with that
 Parameters
 funcsdictionary of function values
 Returns
 objfloat or array
Processed objective(s).
Warning
This function should not need to be called by the user

processXtoDict
(x)[source]¶ Take the flattened array of variables in ‘x’ and return a dictionary of variables keyed on the name of each variable.
 Parameters
 xarray
Flattened array from optimizer
Warning
This function should not need to be called by the user

processXtoVec
(x)[source]¶ Take the dictionary form of x and convert back to flattened array.
 Parameters
 xdict
Dictionary form of variables
 Returns
 x_arrayarray
Flattened array of variables
Warning
This function should not need to be called by the user

setDVs
(inDVs)[source]¶ Set one or more groups of design variables from a dictionary. In most common usage, this function is not required.
 Parameters
 inDVsdict
The dictionary of variables. The keys are the names of the variable groups, and the values are the desired design variable values for each variable group.

setDVsFromHistory
(histFile, key=None)[source]¶ Set optimization variables from a previous optimization. This is like a cold start, but some variables may have been added or removed from the previous optimization. This will try to set all variables it can.
 Parameters
 histFilestr
Filename of the history file to read
 keystr
Key of the history file to use for the x values. The default is None which will use the last xvalue stored in the dictionary.