# Solver¶

The solver module defines the Integral class, which represents an unevaluated integral. This is useful for fully automated solution procedures such as Newton, that require functional derivatives of an entire functional.

To demonstrate this consider the following setup:

>>> from nutils import mesh, function, solver
>>> ns = function.Namespace()
>>> domain, ns.x = mesh.rectilinear([4,4])
>>> ns.basis = domain.basis('spline', degree=2)
>>> cons = domain.boundary['left,top'].project(0, onto=ns.basis, geometry=ns.x, ischeme='gauss4')
project > constrained 11/36 dofs, error 0.00e+00/area
>>> ns.u = 'basis_n ?lhs_n'


Function u represents an element from the discrete space but cannot not evaluated yet as we did not yet establish values for ?lhs. It can, however, be used to construct a residual functional res. Aiming to solve the Poisson problem u_,kk = f we define the residual functional res = v,k u,k + v f and solve for res == 0 using solve_linear:

>>> res = domain.integral('basis_n,i u_,i + basis_n' @ ns, geometry=ns.x, degree=2)
>>> lhs = solver.solve_linear('lhs', residual=res, constrain=cons)
solve > solving system using sparse direct solver


The coefficients lhs represent the solution to the Poisson problem.

In addition to solve_linear the solver module defines newton and pseudotime for solving nonlinear problems, as well as impliciteuler for time dependent problems.

class nutils.solver.Integral(integrands)[source]

Postponed integral, used for derivative purposes

nutils.solver.solve_linear(target, residual, constrain=None, *, arguments=None, **solveargs)[source]

solve linear problem

Parameters: target (str) – Name of the target: a nutils.function.Argument in residual. residual (Integral) – Residual integral, depends on target constrain (float vector) – Defines the fixed entries of the coefficient vector arguments (collections.abc.Mapping) – Defines the values for nutils.function.Argument objects in residual. The target should not be present in arguments. Optional. Array of target values for which residual == 0 vector
nutils.solver.solve(gen_lhs_resnorm, tol=1e-10, maxiter=None)[source]

execute nonlinear solver

Iterates over nonlinear solver until tolerance is reached. Example:

lhs = solve(newton(target, residual), tol=1e-5)

Parameters: gen_lhs_resnorm (generator) – Generates (lhs, resnorm) tuples tol (float) – Target residual norm maxiter (int) – Maximum number of iterations Coefficient vector that corresponds to a smaller than tol residual. vector
nutils.solver.withsolve(f)[source]

add a .solve method to (lhs,resnorm) iterators

Introduces the convenient form:

newton(target, residual).solve(tol)


Shorthand for:

solve(newton(target, residual), tol)

class nutils.solver.newton(*args, **kwargs)[source]

iteratively solve nonlinear problem by gradient descent

Generates targets such that residual approaches 0 using Newton procedure with line search based on a residual integral. Suitable to be used inside solve.

An optimal relaxation value is computed based on the following cubic assumption:

| res(lhs + r * dlhs) |^2 = A + B * r + C * r^2 + D * r^3


where A, B, C and D are determined based on the current and updated residual and tangent.

Parameters: target (str) – Name of the target: a nutils.function.Argument in residual. residual (Integral) – lhs0 (vector) – Coefficient vector, starting point of the iterative procedure. constrain (boolean or float vector) – Equal length to lhs0, masks the free vector entries as False (boolean) or NaN (float). In the remaining positions the values of lhs0 are returned unchanged (boolean) or overruled by the values in constrain (float). nrelax (int) – Maximum number of relaxation steps before proceding with the updated coefficient vector (by default unlimited). minrelax (float) – Lower bound for the relaxation value, to force re-evaluating the functional in situation where the parabolic assumption would otherwise result in unreasonably small steps. maxrelax (float) – Relaxation value below which relaxation continues, unless nrelax is reached; should be a value less than or equal to 1. rebound (float) – Factor by which the relaxation value grows after every update until it reaches unity. arguments (collections.abc.Mapping) – Defines the values for nutils.function.Argument objects in residual. The target should not be present in arguments. Optional. vector – Coefficient vector that approximates residual==0 with increasing accuracy
class nutils.solver.pseudotime(*args, **kwargs)[source]

iteratively solve nonlinear problem by pseudo time stepping

Generates targets such that residual approaches 0 using hybrid of Newton and time stepping. Requires an inertia term and initial timestep. Suitable to be used inside solve.

Parameters: target (str) – Name of the target: a nutils.function.Argument in residual. residual (Integral) – inertia (Integral) – timestep (float) – Initial time step, will scale up as residual decreases lhs0 (vector) – Coefficient vector, starting point of the iterative procedure. constrain (boolean or float vector) – Equal length to lhs0, masks the free vector entries as False (boolean) or NaN (float). In the remaining positions the values of lhs0 are returned unchanged (boolean) or overruled by the values in constrain (float). arguments (collections.abc.Mapping) – Defines the values for nutils.function.Argument objects in residual. The target should not be present in arguments. Optional. vector, float – Tuple of coefficient vector and residual norm
nutils.solver.thetamethod(target, residual, inertia, timestep, lhs0, theta, target0='_thetamethod_target0', constrain=None, newtontol=1e-10, *, arguments=None, **newtonargs)[source]

solve time dependent problem using the theta method

Parameters: target (str) – Name of the target: a nutils.function.Argument in residual. residual (Integral) – inertia (Integral) – timestep (float) – Initial time step, will scale up as residual decreases lhs0 (vector) – Coefficient vector, starting point of the iterative procedure. theta (float) – Theta value (theta=1 for implicit Euler, theta=0.5 for Crank-Nicolson) residual0 (Integral) – Optional additional residual component evaluated in previous timestep constrain (boolean or float vector) – Equal length to lhs0, masks the free vector entries as False (boolean) or NaN (float). In the remaining positions the values of lhs0 are returned unchanged (boolean) or overruled by the values in constrain (float). newtontol (float) – Residual tolerance of individual timesteps arguments (collections.abc.Mapping) – Defines the values for nutils.function.Argument objects in residual. The target should not be present in arguments. Optional. vector – Coefficient vector for all timesteps after the initial condition.
nutils.solver.optimize(target, functional, droptol=None, lhs0=None, constrain=None, newtontol=None, *, arguments=None)[source]

find the minimizer of a given functional

Parameters: target (str) – Name of the target: a nutils.function.Argument in residual. functional (scalar Integral) – The functional the should be minimized by varying target droptol (float) – Threshold for leaving entries in the return value at NaN if they do not contribute to the value of the functional. lhs0 (vector) – Coefficient vector, starting point of the iterative procedure (if applicable). constrain (boolean or float vector) – Equal length to lhs0, masks the free vector entries as False (boolean) or NaN (float). In the remaining positions the values of lhs0 are returned unchanged (boolean) or overruled by the values in constrain (float). newtontol (float) – Residual tolerance of Newton procedure (if applicable) vector – Coefficient vector corresponding to the functional optimum