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

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

solve linear problem

Parameters:
Returns:

Array of target values for which residual == 0

Return type:

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
Returns:

Coefficient vector that corresponds to a smaller than tol residual.

Return type:

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.
Yields:

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.
Yields:

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.
Yields:

vector – Coefficient vector for all timesteps after the initial condition.

nutils.solver.impliciteuler(target, residual, inertia, timestep, lhs0, *, theta=1, target0='_thetamethod_target0', constrain=None, newtontol=1e-10, arguments=None, **newtonargs)

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.
Yields:

vector – Coefficient vector for all timesteps after the initial condition.

nutils.solver.cranknicolson(target, residual, inertia, timestep, lhs0, *, theta=0.5, target0='_thetamethod_target0', constrain=None, newtontol=1e-10, arguments=None, **newtonargs)

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.
Yields:

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)
Yields:

vector – Coefficient vector corresponding to the functional optimum