Y YASPS
Docs menu
Getting started Scene Mesh Primitive Primitive union Connectivity Attribute Minimizer Solver Differentiator Matrix Jacobian Hessian Gradient Examples Dropping in a container Cubify Inverse simulation

API reference · 01

Scene

scene is the root of a YASPS model. It owns meshes, scene-level attributes. Scene also coordinates energy registrations, and minimizations.

from yasps import scene
world = scene("world")

scene

scene(name)

Construct a scene with a given name and register it in the process-wide scene.scenes dictionary.

Parameter Type Description
name str Nonempty scene identifier. Must be unique (two scenes cannot have the same name).

Example

world = scene("world")

Raises: ValueError when name is empty or already registered.

addMesh

addMesh(name)

Create, register, and return a mesh object.

Parameter Type Description
name str Nonempty mesh identifier. Must be unique within the scene.

Example

created_mesh = world.addMesh("m1")
assert world.m1 is created_mesh # m1 can now be accessed as a property of our created scene

Returns: mesh.

Raises: ValueError when the name already exists or fails isValidName.

addAttribute

addAttribute(name, computed_attribute=None, rows=1, cols=1)

Create a scene-level data attribute, or bind a name to an unnamed computed attribute.

Parameter Type Default Description
name str required Name stored in the scene attribute dictionary.
computed_attribute attribute or None None Unnamed symbolic expression to bind. When supplied, rows and cols are ignored.
rows int 1 Per-instance row count for a new data attribute.
cols int 1 Per-instance column count for a new data attribute.

Example

time = world.addAttribute("time")
gravity = world.addAttribute("gravity", rows=3, cols=1)

# binds a computed attribute to the scene with a name
speed = ...
speed_squared = world.addAttribute("speed_squared", computed_attribute=speed * speed)

Returns: attribute.

Raises: ValueError for a duplicate name or when computed_attribute already has a name.

addConstant

addConstant(name, rows=1, cols=1)

Create a constant attribute on the scene. Its value can be updated, but YASPS treats it as constant during differentiation and excludes it from minimization targets.

Parameter Type Default Description
name str required Name stored in the scene attribute dictionary.
rows int 1 Per-instance row count.
cols int 1 Per-instance column count.

Example

dt = world.addConstant("dt")
gravity = world.addConstant("gravity", rows=3, cols=1)

Returns: attribute.

Raises: ValueError for a duplicate name.

__getitem__

scene[key]

Retrieve one named attribute, or pack several named attributes into a single row expression.

Key Result
str The named attribute.
tuple[str, ...] A 1 × N attribute formed by concatenating the named values.

Example

dt = world["dt"]
parameters = world["dt", "gravity"]

Raises: KeyError when a name is missing or the key is neither a string nor tuple.

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)

Register a named scalar(per instance dimension of 1 by 1) attribute as an energy term with the scene’s minimizer.

Parameter Type Default Description
e attribute required Named scalar energy attribute.
targets list[attribute] [] Local differentiation targets required by this energy. Every item must later appear in addMinimizeTarget.
projection_method int 1 Hessian projection: -1 marks that projection is disabled, 0 leaves eigenvalues unchanged, 1 uses absolute eigenvalues, and 2 clamps them to zero. If projection is marked as -1, then later on changing it to 0, 1, or 2 will invoke another code compilation.
save_intermediate bool False Cache intermediate derivative computations in generated code.
gradient_only bool False Reserved option. The current Hessian-based minimizer raises NotImplementedError when this is True.
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 this 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

world.addEnergy(elastic_energy, projection_method=2)
world.addEnergy(contact_energy, targets=[position], dynamic_instances=True)

Returns: None.

Raises: ValueError when the energy is unnamed. TypeError when grouped_add or lto is not a boolean. Further validation happens in the minimizer.

addMinimizeTarget

addMinimizeTarget(target)

Set the ordered global degrees of freedom, then generate the symbolic Hessian and gradient.

Parameter Type Description
target list[attribute] Ordered, unique, static data attributes to solve against. The order determines the returned solution segments.

Call this after registering energies. Every local target passed to addEnergy must appear in this list.

Example

world.addMinimizeTarget([position, affine_dofs])

Returns: None.

Raises: ValueError for duplicates, missing energy targets, non-data attributes, or dynamic attributes.

minimizer.setSolver

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

Select the linear solver through the scene’s minimizer. The default is multilevel additive Schwarz ("mas"). The block-Jacobi PCG solver is available as "jacobian".

Parameter Type Default Description
solver_name str "mas" Solver implementation: "mas" or "jacobian".
**options keyword arguments none Options forwarded to MAS. The Jacobi solver accepts no options.

Example

world.minimizer.setSolver("mas")
print(world.minimizer.solverName)  # mas

world.minimizer.setSolver("jacobian")

MAS keyword options are forwarded to its implementation. The Jacobi solver accepts no options.

Returns: the configured solver dispatcher.

minimizeEnergy

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

Assemble the active Hessian and gradient, solve H x = g, and return one device-array view per minimization target.

Parameter Type Default Description
tolerance float 1e-3 Linear solver convergence tolerance.
maxIterations int 20000 Maximum linear solver iterations.

Example

direction = world.minimizeEnergy(tolerance=1e-6, maxIterations=5000)
position.updateValue(position.value - direction[0], deepCopy=True)

Returns: list[pycuda.gpuarray.GPUArray], aligned with the order supplied to addMinimizeTarget.

YASPS returns the solution direction but does not update target values. When the solver reports a negative error code, the method prints the code and still returns the current solution segments.

computeTotalEnergy

computeTotalEnergy()

Evaluate and sum every active energy on the GPU.

Example

total = world.computeTotalEnergy()

Returns: float.

ignoreEnergies

ignoreEnergies(energies)

Exclude a set of energies from total energy evaluation, as well as Hessian/gradient computation.

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

Example

world.ignoreEnergies([contact_energy])
world.ignoreEnergies([])  # enable every registered energy again

Returns: None.

Properties

Property Type Description
name str Scene identifier supplied to the constructor.
scene scene This scene itself.
type str Always "scene".
attributes dict[str, attribute] Named attributes and constants registered at scene scope.
minimizer minimizer Scene-owned minimizer used to select or inspect the linear solver.
numInstances int Always 1. Any attribute created at scene scope has one instance.
numMeshes int Number of mesh objects created by addMesh.
fullName str Same value as name.
energies dict[str, attribute] Scene energy dictionary. addEnergy currently registers requests on minimizer instead.
gradientSegments list[pycuda.gpuarray.GPUArray] Gradient views aligned with the minimization targets. This is empty before target initialization.
gradient pycuda.gpuarray.GPUArray Flat gradient value array, an empty device array before initialization.