assemble(form, tensor=None, mesh=None, coefficients=None, function_spaces=None, cell_domains=None, exterior_facet_domains=None, interior_facet_domains=None, reset_sparsity=True, add_values=False, finalize_tensor=True, keep_diagonal=False, backend=None, form_compiler_parameters=None, bcs=None)¶
Assemble the given form and return the corresponding tensor.
- Depending on the input form, which may be a functional, linear form, bilinear form or higher rank form, a scalar value, a vector, a matrix or a higher rank tensor is returned.
In the simplest case, no additional arguments are needed. However, additional arguments may and must in some cases be provided as outlined below.
formcan be either an FFC form or a precompiled UFC form. If a precompiled or ‘pure’ UFC form is given, then
function_spaceshave to be provided too. The coefficient functions should be provided as a ‘dict’ using the FFC functions as keys. The function spaces should be provided either as a list where the number of function spaces must correspond to the number of basis functions in the form, or as a single argument, implying that the same FunctionSpace is used for all test/trial spaces.
If the form defines integrals over different subdomains,
MeshFunctionsover the corresponding topological entities defining the subdomains can be provided. An instance of a
SubDomaincan also be passed for each subdomain.
The implementation of the returned tensor is determined by the default linear algebra backend. This can be overridden by specifying a different backend.
Each call to assemble() will create a new tensor. If the
tensorargument is provided, this will be used instead. If
reset_sparsityis set to False, the provided tensor will not be reset to zero before assembling (adding) values to the tensor.
keep_diagonalis set to True, assembler ensures that potential zeros on a matrix diagonal are kept in sparsity pattern so every diagonal entry can be changed in a future (for example by ident() or ident_zeros()).
Specific form compiler parameters can be provided by the
form_compiler_parametersargument. Form compiler parameters can also be controlled using the global parameters stored in parameters[“form_compiler”].
- Examples of usage
The standard stiffness matrix
Aand a load vector
bcan be assembled as follows:
A = assemble(inner(grad(u),grad(v))*dx()) b = assemble(f*v*dx())
It is possible to explicitly prescribe the domains over which integrals wll be evaluated using the arguments
interior_facet_domains. For instance, using a mesh function marking parts of the boundary:
# MeshFunction marking boundary parts boundary_parts = MeshFunction("size_t", mesh, mesh.topology().dim()-1) # Sample variational forms a = inner(grad(u), grad(v))*dx() + p*u*v*ds(0) L = f*v*dx() - g*v*ds(1) + p*q*v*ds(0) A = assemble(a, exterior_facet_domains=boundary_parts) b = assemble(L, exterior_facet_domains=boundary_parts)
To ensure that the assembled matrix has the right type, one may use the
A = PETScMatrix() assemble(a, tensor=A)
ais now assembled into the PETScMatrix