warp.fem.integrate#

warp.fem.integrate(
integrand,
domain=None,
quadrature=None,
fields=None,
values=None,
accumulate_dtype=warp.float64,
output_dtype=None,
output=None,
device=None,
temporary_store=None,
kernel_options=None,
assembly=None,
add=False,
bsr_options=None,
)[source]#

Integrates a constant, linear or bilinear form, and returns a scalar, array, or sparse matrix, respectively.

Parameters:

  • integrand (Integrand) – Form to be integrated, must have integrand() decorator

  • domain (GeometryDomain | None) – Integration domain. If None, deduced from fields

  • quadrature (Quadrature | None) – Quadrature formula. If None, deduced from domain and fields degree.

  • fields (dict[str, FieldLike] | None) – Discrete, test, and trial fields to be passed to the integrand. Keys in the dictionary must match integrand parameter names.

  • values (dict[str, Any] | None) – Additional variable values to be passed to the integrand, can be of any type accepted by warp kernel launches. Keys in the dictionary must match integrand parameter names.

  • temporary_store (TemporaryStore | None) – shared pool from which to allocate temporary arrays

  • accumulate_dtype (type) – Scalar type to be used for accumulating integration samples

  • output (BsrMatrix | array | None) – Sparse matrix or warp array into which to store the result of the integration

  • output_dtype (type | None) – Scalar type for returned results if output is not provided. If None, defaults to the geometry’s scalar type (warp.float32 or warp.float64)

  • device – Device on which to perform the integration

  • kernel_options (dict[str, Any] | None) – Overloaded options to be passed to the kernel builder (e.g, {"enable_backward": True})

  • assembly (str | None) – Specifies the strategy for assembling the integrated vector or matrix: - “nodal”: For linear or bilinear forms, use the test function nodes as the quadrature points. Assumes Lagrange interpolation functions are used, and no differential or DG operator is evaluated on the test or trial functions. - “generic”: Single-pass integration and shape-function evaluation. Makes no assumption about the integrand’s content, but may lead to many redundant computations. - “dispatch”: For linear or bilinear forms, first evaluate the form at quadrature points then dispatch to nodes in a second pass. More efficient for integrands that are expensive to evaluate. Incompatible with at_node and node_index operators on test or trial functions. - None (default): Automatically picks a suitable assembly strategy (either “generic” or “dispatch”)

  • add (bool) – If True and output is provided, add the integration result to output instead of replacing its content

  • bsr_options (dict[str, Any] | None) – Additional options to be passed to the sparse matrix construction algorithm. See warp.sparse.bsr_set_from_triplets() and warp.sparse.bsr_compress(). In addition to sparse options, capacity="auto" allows FEM to grow sparse storage as needed, while capacity="reuse" requires existing output arrays to be large enough and does not grow them. Omitting construction uses "triplets". construction="auto" opts into automatic selection of a suitable construction method, whose choices may change in future releases; currently it uses row compression for bilinear assembly when possible. construction="triplets" forces temporary COO triplet construction, while construction="row_compress" forces row-ordered candidate writes followed by warp.sparse.bsr_compress(). For row compression, warp.sparse.bsr_compress() uses inplace=False when output.values.requires_grad is true; non-differentiable outputs use in-place compression for the lowest memory overhead. construction="mapped" assembles from triplets and caches the resulting triplet-to-block map (see build_mapping in warp.sparse.bsr_set_from_triplets()) when capacity="auto"; calls with capacity="reuse" on the same output matrix then skip topology construction and perform atomic-free gather reduction through the cached map. construction="mapped_atomic" reuses the same map and fuses atomic accumulation directly into the integration kernel, avoiding temporary triplet-value storage. Its floating-point accumulation order is non-deterministic; use construction="mapped" when run-to-run deterministic reduction is required. Both mapped policies require compact topology. They are intended for repeated assembly whose mesh, spaces, restrictions, and quadrature topology remain unchanged; call again with capacity="auto" to rebuild the map after any of those change. Building the map does not synchronize with the host; calling output.nnz_sync() once after it has been built tightens the launch dimensions of subsequent mapped assemblies. Between mapped calls, no other operation may modify the output matrix, including another integrate() or interpolate() call writing through a different assembly strategy, and the mapped assembly strategy must remain unchanged. Non-mapped FEM writes invalidate the cached map, but in-place changes made by custom kernels or external libraries cannot be detected; violating this requirement has undefined behavior.

On this page