desc.objectives.ObjectiveFunction

class desc.objectives.ObjectiveFunction(objectives, use_jit=True, deriv_mode='auto', name='ObjectiveFunction', jac_chunk_size='auto')Source

Objective function comprised of one or more Objectives.

Parameters:

• objectives (tuple of Objective) – List of objectives to be minimized.

• use_jit (bool, optional) – Whether to just-in-time compile the objectives and derivatives.

• deriv_mode ({"auto", "batched", "blocked"}) – Method for computing Jacobian matrices. batched uses forward mode, applied to the entire objective at once, and is generally the fastest for vector valued objectives. Its memory intensity vs. speed may be traded off through the jac_chunk_size keyword argument. “blocked” builds the Jacobian for each objective separately, using each objective’s preferred AD mode (and each objective’s jac_chunk_size). Generally the most efficient option when mixing scalar and vector valued objectives. auto defaults to batched if all sub-objectives are set to fwd, otherwise blocked.

• name (str) – Name of the objective function.

• jac_chunk_size (int or auto, optional) – If batched deriv_mode is used, will calculate the Jacobian jac_chunk_size columns at a time, instead of all at once. The memory usage of the Jacobian calculation is roughly memory usage = m0+m1*jac_chunk_size: the smaller the chunk size, the less memory the Jacobian calculation will require (with some baseline memory usage). The time it takes to compute the Jacobian is roughly t = t0+t1/jac_chunk_size so the larger the jac_chunk_size, the faster the calculation takes, at the cost of requiring more memory. If None, it will use the largest size i.e obj.dim_x. Can also help with Hessian computation memory, as Hessian is essentially jacfwd(jacrev(f)), and each of these operations may be chunked. Defaults to chunk_size="auto". Note: When running on a CPU (not a GPU) on a HPC cluster, DESC is unable to accurately estimate the available device memory, so the “auto” chunk_size option will yield a larger chunk size than may be needed. It is recommended to manually choose a chunk_size if an OOM error is experienced in this case.

Methods

build([use_jit, verbose])	Build the objective.
compile([mode, verbose])	Call the necessary functions to ensure the function is compiled.
compute_scalar(x[, constants])	Compute the sum of squares error.
compute_scaled(x[, constants])	Compute the objective function and apply weighting and normalization.
compute_scaled_error(x[, constants])	Compute and apply the target/bounds, weighting, and normalization.
compute_unscaled(x[, constants])	Compute the raw value of the objective function.
copy([deepcopy])	Return a (deep)copy of this object.
equiv(other)	Compare equivalence between DESC objects.
grad(x[, constants])	Compute gradient vector of self.compute_scalar wrt x.
hess(x[, constants])	Compute Hessian matrix of self.compute_scalar wrt x.
jac_scaled(x[, constants])	Compute Jacobian matrix of self.compute_scaled wrt x.
jac_scaled_error(x[, constants])	Compute Jacobian matrix of self.compute_scaled_error wrt x.
jac_unscaled(x[, constants])	Compute Jacobian matrix of self.compute_unscaled wrt x.
jvp_scaled(v, x[, constants])	Compute Jacobian-vector product of self.compute_scaled.
jvp_scaled_error(v, x[, constants])	Compute Jacobian-vector product of self.compute_scaled_error.
jvp_unscaled(v, x[, constants])	Compute Jacobian-vector product of self.compute_unscaled.
load(load_from[, file_format])	Initialize from file.
print_value(x[, x0, constants])	Print the value(s) of the objective.
save(file_name[, file_format, file_mode])	Save the object.
unpack_state(x[, per_objective])	Unpack the state vector into its components.
vjp_scaled(v, x[, constants])	Compute vector-Jacobian product of self.compute_scaled.
vjp_scaled_error(v, x[, constants])	Compute vector-Jacobian product of self.compute_scaled_error.
vjp_unscaled(v, x[, constants])	Compute vector-Jacobian product of self.compute_unscaled.
x(*things)	Return the full state vector from the Optimizable objects things.

Attributes

bounds_scaled	lower and upper bounds for residual vector.
built	Whether the objectives have been built or not.
compiled	Whether the functions have been compiled or not.
constants	constant parameters for each sub-objective.
dim_f	Number of objective equations.
dim_x	Dimensional of the state vector.
name	Name of objective function (str).
objectives	List of objectives.
scalar	Whether default "compute" method is a scalar or vector.
target_scaled	target vector.
things	Unique list of optimizable things that this objective is tied to.
use_jit	Whether to just-in-time compile the objective and derivatives.
weights	weight vector.