API reference · 09

Differentiator

Differentiate symbolic attributes once or twice to create gradients, jacobians, and Hessians for GPU assembly.

differentiator

differentiator()

Create a stateless public differentiation entry point. Each call to diff1 or diff2 builds a new derivative object.

Example

autodiff = differentiator()

Returns: new differentiator.

diff1

diff1(source, global_targets, local_targets=[], dynamic_instances=False)

Differentiate a source once. Scalar sources produce a gradient; vector-valued sources produce a first-order jacobian.

Parameter	Type	Default	Description
`source`	attribute or `list[attribute]`	required	Scalar source terms to sum, or vector-valued sources with matching roles.
`global_targets`	`list[attribute]`	required	Ordered attributes to differentiate with respect to.
`local_targets`	`list[attribute]`	`[]`	Optional local targets for scalar-gradient differentiation. Not supported for vector-valued sources.
`dynamic_instances`	`bool`	`False`	Mark derivative terms whose source instances or connectivity change at runtime.

Source	Returns
Scalar attribute or scalar list	gradient
Vector-valued attribute or vector-valued list	first-order jacobian

Example

initial_mapping_jacobian = differentiator().diff1(initial_position_mapping, [initial_translation_parameter])

Raises: ValueError for empty targets, mixed scalar and vector sources, unsupported local vector targets, or invalid target attributes.

diff2

diff2(source, target1, target2, local_targets=[], projection_method=1, save_intermediate=False, separate_hessian_jacobian=False, dynamic_instances=False, grouped_add=False, lto=False)

Differentiate scalar sources twice. Matching target lists produce a hessian; different row and column targets produce a mixed second-order jacobian.

Parameter	Type	Default	Description
`source`	attribute or `list[attribute]`	required	Scalar source terms to differentiate and sum.
`target1`	`list[attribute]`	required	Ordered row targets.
`target2`	`list[attribute]`	required	Ordered column targets. An identical list selects hessian generation.
`local_targets`	`list[attribute]`	`[]`	Optional local differentiation targets used by hessian generation.
`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.
`separate_hessian_jacobian`	`bool`	`False`	Store the local Hessian and jacobian separately, then multiply them during global assembly. This can reduce generated storage when the jacobian is large but the local Hessian is small.
`dynamic_instances`	`bool`	`False`	Mark terms whose source instances or connectivity change at runtime.
`grouped_add`	`bool`	`False`	Combine same-address contributions within a CUDA warp before one atomic addition. This preserves the mathematical result and may improve highly contended Hessian assembly.
`lto`	`bool`	`False`	Enable link-time optimization in supported generated paths.

Targets	Returns
`target1` and `target2` match	hessian
`target1` and `target2` differ	second-order jacobian

Example

elastic_hessian = differentiator().diff2([elastic_energy], [position], [position], projection_method=1)

previous_position_jacobian = differentiator().diff2([inertia_energy], [position], [last_position])

Raises: ValueError for empty sources or invalid targets; TypeError when hessian-only boolean options are not booleans.