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.

nutils.solver.
solve_linear
(target, residual, constrain=None, *, arguments=None, **solveargs)[source]¶ solve linear problem
Parameters:  target (
str
) – Name of the target: anutils.function.Argument
inresidual
.  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 fornutils.function.Argument
objects in residual. Thetarget
should not be present inarguments
. Optional.
Returns: Array of
target
values for whichresidual == 0
Return type: vector
 target (

nutils.solver.
solve
(gen_lhs_resnorm, tol=1e10, maxiter=None)[source]¶ execute nonlinear solver
Iterates over nonlinear solver until tolerance is reached. Example:
lhs = solve(newton(target, residual), tol=1e5)
Parameters: 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
andD
are determined based on the current and updated residual and tangent.Parameters:  target (
str
) – Name of the target: anutils.function.Argument
inresidual
.  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 asFalse
(boolean) or NaN (float). In the remaining positions the values oflhs0
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 reevaluating 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 fornutils.function.Argument
objects in residual. Thetarget
should not be present inarguments
. Optional.
Yields: vector – Coefficient vector that approximates residual==0 with increasing accuracy
 target (

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: anutils.function.Argument
inresidual
.  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 asFalse
(boolean) or NaN (float). In the remaining positions the values oflhs0
are returned unchanged (boolean) or overruled by the values in constrain (float).  arguments (
collections.abc.Mapping
) – Defines the values fornutils.function.Argument
objects in residual. Thetarget
should not be present inarguments
. Optional.
Yields: vector, float – Tuple of coefficient vector and residual norm
 target (

nutils.solver.
thetamethod
(target, residual, inertia, timestep, lhs0, theta, target0='_thetamethod_target0', constrain=None, newtontol=1e10, *, arguments=None, **newtonargs)[source]¶ solve time dependent problem using the theta method
Parameters:  target (
str
) – Name of the target: anutils.function.Argument
inresidual
.  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 CrankNicolson)
 residual0 (Integral) – Optional additional residual component evaluated in previous timestep
 constrain (boolean or float vector) – Equal length to
lhs0
, masks the free vector entries asFalse
(boolean) or NaN (float). In the remaining positions the values oflhs0
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 fornutils.function.Argument
objects in residual. Thetarget
should not be present inarguments
. Optional.
Yields: vector – Coefficient vector for all timesteps after the initial condition.
 target (

nutils.solver.
impliciteuler
(target, residual, inertia, timestep, lhs0, *, theta=1, target0='_thetamethod_target0', constrain=None, newtontol=1e10, arguments=None, **newtonargs)¶ solve time dependent problem using the theta method
Parameters:  target (
str
) – Name of the target: anutils.function.Argument
inresidual
.  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 CrankNicolson)
 residual0 (Integral) – Optional additional residual component evaluated in previous timestep
 constrain (boolean or float vector) – Equal length to
lhs0
, masks the free vector entries asFalse
(boolean) or NaN (float). In the remaining positions the values oflhs0
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 fornutils.function.Argument
objects in residual. Thetarget
should not be present inarguments
. Optional.
Yields: vector – Coefficient vector for all timesteps after the initial condition.
 target (

nutils.solver.
cranknicolson
(target, residual, inertia, timestep, lhs0, *, theta=0.5, target0='_thetamethod_target0', constrain=None, newtontol=1e10, arguments=None, **newtonargs)¶ solve time dependent problem using the theta method
Parameters:  target (
str
) – Name of the target: anutils.function.Argument
inresidual
.  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 CrankNicolson)
 residual0 (Integral) – Optional additional residual component evaluated in previous timestep
 constrain (boolean or float vector) – Equal length to
lhs0
, masks the free vector entries asFalse
(boolean) or NaN (float). In the remaining positions the values oflhs0
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 fornutils.function.Argument
objects in residual. Thetarget
should not be present inarguments
. Optional.
Yields: vector – Coefficient vector for all timesteps after the initial condition.
 target (

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: anutils.function.Argument
inresidual
.  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 asFalse
(boolean) or NaN (float). In the remaining positions the values oflhs0
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
 target (