class pygeo.parameterization.DVGeoESP.DVGeometryESP(fileName, comm=mpi4py.MPI.COMM_WORLD, scale=1.0, bodies=[], projTol=0.01, debug=False, maxproc=None, suppress_stdout=False, exclude_edge_projections=False, ulimits=None, vlimits=None, name=None)[source]

A class for manipulating Engineering Sketch Pad (ESP) geometry. The purpose of the DVGeometryESP class is to provide translation of the ESP geometry engine to externally supplied surfaces. This allows the use of ESP design parameters to control the MACH framework.

There are several important limitations:

  1. Since ESP is surface based only, it cannot be used to parameterize a geometry that doesn’t lie on the surface. Structural members need to be directly modeled in ESP as surfaces.

  2. It cannot handle moving intersection. A geometry with static intersections is fine as long as the intersection doesn’t move.

  3. It does not support complex numbers for the complex-step method.

  4. It does not support separate configurations.


filename of .csm file containing the parameterized CAD

commMPI Intra Comm

Comm on which to build operate the object. This is used to perform embarrassingly parallel finite differencing. Defaults to MPI.COMM_WORLD.


A global scale factor from the ESP geometry to incoming (CFD) mesh geometry. For example, if the ESP model is in inches, and the CFD in meters, scale=0.0254.

bodieslist of strings

A list of the names of the ESP bodies to consider. They need to be on the top of the ESP body stack (i.e., visible in the ESP user interface when all the branches are built)


The maximum allowable error between point sets and the projected points. If exceeded, returns an error during addPointSet(). Default 0.01.


Maximum number of processors to use in the finite difference. Default no limit.


Suppress console output from ESP. Default False.


Disallow projections to edges in the ESP topology (only allow surfaces). This can sometimes fix weird mesh deformation issues near the mesh boundaries. Default False.


The general sequence of operations for using DVGeometry is as follows:

>>> from pygeo import DVGeometryESP
>>> DVGeo = DVGeometryESP("wing.csm", MPI_COMM_WORLD)
>>> # Add a set of coordinates Xpt into the object
>>> DVGeo.addPointSet(Xpt, 'myPoints')
addPointSet(points, ptName, distributed=True, cache_projections=False, **kwargs)[source]

Add a set of coordinates to DVGeometryESP. The is the main way that geometry, in the form of a coordinate list, is given to DVGeometry to be manipulated.

pointsarray, size (N,3)

The coordinates to embed. These coordinates should all project into the interior of the ESP model volume.


A user supplied name to associate with the set of coordinates. This name will need to be provided when updating the coordinates or when getting the derivatives of the coordinates.


Whether the pointset is distributed (different each proc) or non-distributed (duplicated and identical each proc). Should be set to false for duplicated pointsets to avoid very poor parallel scaling in the derivatives routine.

cache_projectionsNone or str

The user can optionally cache the point set projections to save initialization time. If a filename is provided, the cached u, v, t coordinates will be saved in numpy compressed format (‘.npz’ extension should be used). The points will be validated to ensure that the projections remain within tolerance of the model and if not, the projections will be recreated.

addVariable(desmptr_name, name=None, value=None, lower=None, upper=None, scale=1.0, rows=None, cols=None, dh=0.001)[source]

Add an ESP design parameter to the DVGeo problem definition. The name of the parameter must match a despmtr in the CSM file of the CAD model.

Array-valued desmptrs can be handled in one of four ways:

  • rows=None, cols=None (default): treats the entire array as a flat vector

  • rows=[1, 2, 3], cols=None: pick specific rows (all cols included)

  • rows=[1, 2, 3], cols=[2, 4]: pick specific rows and columns

  • rows=[1], cols=[2]: pick a specific value


The indices are 1-indexed (per the OpenCSM standard)!! They are not 0-indexed.

The design variable vector passed to pyOptSparse will be in row-major order. In other words, the vector will look like: [a(1, 1), a(1, 2), a(1, 3), a(2, 1), a(2, 2), a(2, 3), a(3, 1), ….]

The value, upper, and lower bounds must all be of length len(rows)*len(cols).


Name of the ESP design parameter.

namestr or None

Human-readable name for this design variable (default same as``despmtr``).

valuefloat or None

The design variable. If this value is not supplied (None), then the current value in the ESP model will be queried and used.

lowerfloat or None

Lower bound for the design variable. Use None for no lower bound.

upperfloat or None

Upper bound for the design variable. Use None for no upper bound.


Scale factor sent to pyOptSparse and used in optimization.

rowslist or None

Design variable row index(indices) to use. Default None uses all rows.

colslist or None

Design variable col index(indices) to use. Default None uses all cols.


Finite difference step size. Default 0.001.


Return the number of DVs.


Number of design variables.


Print a formatted list of design variables to the screen

setDesignVars(dvDict, updateJacobian=True)[source]

Standard routine for setting design variables from a design variable dictionary.


Dictionary of design variables. The keys of the dictionary must correspond to the design variable names. Any additional keys in the dfvdictionary are simply ignored.

totalSensitivity(dIdpt, ptSetName, comm=None, config=None)[source]

This function computes sensitivity information. Specifically, it computes the following: \(\frac{dI}{d_{pt}}\frac{dX_{pt}}{dX_{DV}}\)

dIdptarray of size (Npt, 3) or (N, Npt, 3)

This is the total derivative of the objective or function of interest with respect to the coordinates in ptSetName. This can be a single array of size (Npt, 3) or a group of N vectors of size (Npt, 3, N). If you have many to do, it is faster to do many at once.


The name of set of points we are dealing with.


The communicator to use to reduce the final derivative. If comm is None, no reduction takes place.


The dictionary containing the derivatives, suitable for pyOptSparse.

totalSensitivityProd(vec, ptSetName, comm=None, config=None)[source]

This function computes sensitivity information. Specifically, it computes the following: \(\frac{dX_{pt}}{dX_{DV}} \vec'\)


Keys are the design variable names and values are the derivative seeds of the corresponding design variable.


The name of set of points we are dealing with.


The communicator to use to reduce the final derivative. If comm is None, no reduction takes place.

xsdotarray (Nx3)

Array with derivative seeds of the surface nodes.

update(ptSetName, config=None)[source]

This is the main routine for returning coordinates that have been updated by design variables. Multiple configs are not supported.


Name of pointset to return. This must match ones of the given in an addPointSet() call.


Write out the ESP model to a CAD format supported by ESP


Name of CAD file including valid file extension.


Writes the current state of design variables in the ESP model to a CSM file.


Name of CSM file to write ESP model to.