API reference · 07

Minimizer

Register symbolic energies and target attributes, assemble their hessian and gradient, and invoke the selected linear solver.

A scene owns one minimizer and exposes it through scene.minimizer. Direct construction is useful when an example needs several independent objectives.

minimizer

minimizer()

Create an empty minimizer using the default MAS solver.

Example

local_minimizer = minimizer()
global_minimizer = minimizer()

Returns: new minimizer.

setSolver

setSolver(solver_name="mas", **options)

Replace the current linear solver and clear its cached solution layout.

Parameter	Type	Default	Description
`solver_name`	`str`	`"mas"`	Solver implementation: `"mas"` or `"jacobian"`.
`**options`	keyword arguments	none	Options forwarded to the MAS implementation. The jacobian solver accepts no options. See the MAS options for details about the MAS solver options.

Example

local_minimizer.setSolver("mas")

Returns: selected solver.

addEnergy

addEnergy(e, targets=[], projection_method=1, save_intermediate=False, gradient_only=False, dynamic_instances=False, separate_hessian_jacobian=False, grouped_add=False, lto=False)

Parameter	Type	Default	Description
`e`	attribute	required	Named scalar energy attribute.
`targets`	`list[attribute]`	`[]`	Local targets required by this energy. Every item must later appear in `addWrt`.
`projection_method`	`int`	`1`	Hessian projection: `-1` disables projection, `0` keeps eigenvalues, `1` takes their absolute values, and `2` clamps negative values to zero.
`save_intermediate`	`bool`	`False`	Save intermediate derivative computations.
`gradient_only`	`bool`	`False`	Reserved; `True` is not supported by the hessian-based minimizer.
`dynamic_instances`	`bool`	`False`	Mark an energy whose instance count or connectivity changes at runtime.
`separate_hessian_jacobian`	`bool`	`False`	Generate separate Hessian and jacobian paths.
`grouped_add`	`bool`	`False`	Use grouped assembly for the energy.
`lto`	`bool`	`False`	Enable link-time optimization in supported generated paths.

See differentiator.diff2 for details about separate_hessian_jacobian and grouped_add.

Example

local_minimizer.addEnergy(cubic_energy, projection_method=2)
local_minimizer.addEnergy(contact_energy, dynamic_instances=True)

Returns: None.

Raises: ValueError when the energy is unnamed or already registered; NotImplementedError when gradient_only=True.

addWrt

addWrt(wrt)

Set the ordered, static data attributes to differentiate and solve with respect to. Their order determines the gradient and solution segments.

Parameter	Type	Description
`wrt`	`list[attribute]`	Unique, non-dynamic data attributes containing every local target required by the registered energies.

Example

local_minimizer.addWrt([rotation])
global_minimizer.addWrt([position])

Returns: None.

Raises: ValueError for duplicate, symbolic, dynamic, or missing target attributes.

generateHessianAndGradient

generateHessianAndGradient()

Differentiate the registered energies and prepare their symbolic hessian and gradient structures. Numeric values are assembled later.

Example

local_minimizer.generateHessianAndGradient()

Returns: None.

computeSolution

computeSolution(tolerance=1e-3, maxIterations=20000)

Assemble the current hessian and gradient, solve the linear system, and return one device-array view per target in wrt.

Parameter	Type	Default	Description
`tolerance`	`float`	`1e-3`	Solver convergence tolerance.
`maxIterations`	`int`	`20000`	Maximum PCG iterations.

Example

rotation_step = local_minimizer.computeSolution()[0]

Returns: list[pycuda.gpuarray.GPUArray] ordered like wrt.

ignoreEnergies

ignoreEnergies(energies)

Exclude selected energy attributes from assembly and total-energy evaluation. Passing an empty list enables every registered energy again.

Parameter	Type	Description
`energies`	`list[attribute]`	Registered energy attributes to ignore.

Example

local_minimizer.ignoreEnergies([contact_energy])
local_minimizer.ignoreEnergies([])

Returns: None.

computeTotalEnergy

computeTotalEnergy()

Compute and sum every active energy value on the GPU.

Example

energy_before = local_minimizer.computeTotalEnergy()

Returns: float.

Properties

Property	Type	Description
`solutionSegments`	`list[pycuda.gpuarray.GPUArray]`	Views into the current solution, ordered like `wrt`.
`linearSolver`	solver	Active linear solver; assigning a compatible solver resets cached solution buffers.
`solverName`	`str`	Name reported by the active solver.
`gradient`	`pycuda.gpuarray.GPUArray`	Flat numeric gradient; empty before assembly.
`gradientSegments`	`list[pycuda.gpuarray.GPUArray]`	Gradient views ordered like `wrt`.
`energies`	`list[energy request]`	Registered static energy requests.
`energiesDynamic`	`list[energy request]`	Registered dynamic energy requests.
`wrt`	`list[attribute]`	Ordered differentiation targets.
`diagonal`	`pycuda.gpuarray.GPUArray`	Active hessian diagonal; empty before assembly.