5.1.1.4. spitfire.time package¶

5.1.1.4.1. Submodules¶

5.1.1.4.2. spitfire.time.integrator module¶

This module contains the time integration governor abstraction, which combines time steppers, nonlinear solvers, and step controllers into a generic integration loop that supports arbitrary in situ processing, logging, termination of the integration loop, and more. For instance, evaluation of the linear operator (Jacobian/preconditioner evaluation and factorization) in implicit methods is guided by the Governor, as it can oversee the entire integration. In many cases the Jacobian/preconditioner can be lagged for several time steps to speed up the integration process substantially.

exception spitfire.time.integrator.FailedODESolveException(msg, times, states)¶

Bases: ValueError

property states¶

property times¶

spitfire.time.integrator.odesolve(right_hand_side, initial_state, output_times=None, save_each_step=False, initial_time=0.0, stop_criteria=None, stop_at_time=None, stop_at_steady=None, minimum_time_step_count=0, maximum_time_step_count=inf, pre_step_callback=None, post_step_callback=None, step_update_callback=None, method=<spitfire.time.methods.KennedyCarpenterS6P4Q3 object>, step_size=<spitfire.time.stepcontrol.PIController object>, linear_setup=None, linear_solve=None, linear_setup_rate=1, mass_setup=None, mass_matvec=None, verbose=False, debug_verbose=False, log_rate=1, log_lines_per_header=10, extra_logger_title_line1=None, extra_logger_title_line2=None, extra_logger_log=None, norm_weighting=1.0, strict_temporal_error_control=False, nonlinear_solve_must_converge=False, warn_on_failed_step=False, return_on_failed_step=False, time_step_reduction_factor_on_failure=0.8, time_step_reduction_factor_on_slow_solve=0.8, time_step_increase_factor_to_force_jacobian=1.05, time_step_decrease_factor_to_force_jacobian=0.9, show_solver_stats_in_situ=False, return_info=False, throw_on_failure=True, print_exception_on_failure=True, maximum_residual=None)¶

Solve a time integration problem with a wide variety of solvers, termination options, etc.

Parameters:

right_hand_sidecallable f(t,q)->r: the right-hand side of the ODE system, in the form f(t, y)
initial_statenp.ndarray: the initial state vector
output_timesnp.array: a collection of times at which the state will be returned
save_each_stepbool/Int
set to True to save all data at each time step, or set to a positive integer to specify a step frequency of saving data
initial_timefloat: the initial time
stop_criteriacallable(q, t, dt, nt, res)->bool: any data with a call operator (state, t, dt, nt, residual) that returns True to stop time integration
stop_at_timebool: force time integration to stop at exactly the provided final time
stop_at_steadybool: force time integration to stop when a steady state is identified, provide either a boolean or a float for the tolerance
minimum_time_step_countInt: minimum number of time steps that can be run (default: 0)
maximum_time_step_countInt: maximum number of time steps that can be run (default: Inf)
pre_step_callbackcallable f(t,q,nt): method of the form f(current_time, current_state, number_of_time_steps) called before each step (default: None)
post_step_callbackcallable f(t,q,r,nt): method of the form f(current_time, current_state, residual, number_of_time_steps) called after each step, that can optionally return a modified state vector (default: None)
step_update_callbackcallable f(q,dq,e,te,nsc): method of the form f(state, dstate, time_error, target_error, nonlinear_solve_converged) that checks validity of a state update (default: None)
methodspitfire.time.methods.TimeStepper instance: the time stepper method, defaults to KennedyCarpenterS6P4Q3(SimpleNewtonSolver())
step_sizefloat/spitfire.time.stepcontrol: the time step controller, either a float (for constant time step) or spitfire.time.stepcontrol class
linear_setupcallable f(t,y,scale): the linear system setup method, in the form f(t, y, scale), to set up a (scale * J - M) operator
linear_solvecallable f(res)->sol: the linear system solve method, in the form f(residual), to solve (scale * J - M)x = b
linear_setup_rateInt: the largest number of steps that can occur before setting up the linear projector (default: 1 (every step))
mass_setupcallable f(t,y): the setup method for the mass matrix/operator, in the form f(t, y), not supported yet, but hopefully soon…
mass_matveccallabele f(x)->b: the matrix-vector product operator for the mass matrix, in the form f(x) to produce M.dot(x), not supported yet, but hopefully soon…
verbosebool: whether or not to continually write out the integrator status and some statistics, turn off for best performance (default: False)
debug_verbosebool: whether or not to write A LOT of information during integration, do not use in any normal situation (default: False)
log_rateInt: how frequently verbose output should be written, increase or turn off output for best performance (default: 1 = every step)
log_lines_per_headerInt: how many log lines are written between rewriting the header (default: 10)
extra_logger_title_line1str: the first line to place above the extra_logger_log text
extra_logger_title_line2str: the second line to place above the extra_logger_log text
extra_logger_logcallable f(q,t,nt,nni,nli): a method of form f(state, time, n_steps, number_nonlinear_iter, number_linear_iter) that adds to the log output
return_infobool: whether or not to return solver statistics (default: False)
norm_weightingfloat/np.ndarray: how the temporal error estimate is weighted in its norm calculation, can be a float or np.array (default: 1)
strict_temporal_error_controlbool: whether or not to enforce that error-controlled adaptive time stepping keeps the error estimate below the target (default: False)
nonlinear_solve_must_convergebool: whether or not the nonlinear solver in each time step of implicit methods must converge (default: False)
warn_on_failed_stepbool: whether or not to print a warning when a step fails (default: False)
return_on_failed_stepbool: whether or not to return and stop integrating when a step fails (default: False)
time_step_reduction_factor_on_failurefloat: factor used in reducing the step size after a step fails, if not returning on failure (default: 0.8)
time_step_reduction_factor_on_slow_solvefloat: factor used in reducing the step size after a step is deemed slow by the nonlinear solver (default: 0.8)
time_step_increase_factor_to_force_jacobianfloat: how much the time step size must increase on a time step to force setup of the projector (default: 1.05)
time_step_decrease_factor_to_force_jacobianfloat: how much the time step size must decrease on a time step to force setup of the projector (default: 0.9)
show_solver_stats_in_situbool: whether or not to include the number of nonlinear iterations per step, linear iterations per nonlinear iteration, number of time steps per Jacobian evaluation (projector setup) in the logged output (default: False)
return_infobool: whether or not to return a dictionary of solver statistics
throw_on_failurebool: whether or not to throw an exception on integrator/model failure (default: True)
print_exception_on_failurebool: whether or not to print an exception message on integrator/model failure (default: True)
maximum_residualfloat: maximum allowed residual to continue time stepping (default: None)

Returns:

Depending on the inputs:

output_times is provided: returns an array of output states, and the solver stats dictionary if return_info is True
save_each_step is True (or a positive integer frequency): returns an array of times, and an array of output states, and the solver stats dictionary if return_info is True
else: returns the final state vector, final time, and final time step, and the solver stats dictionary if return_info is True

5.1.1.4.3. spitfire.time.methods module¶

This module contains time stepping methods that represent distinct methods of taking a single step in the time integration loop. Some are explicit, some are implicit. Some allow adaptive time stepping via control of embedded temporal error estimates while most do not.

Consider a general purpose explicit ODE,

(5.1)¶\[\frac{\partial \boldsymbol{q}}{\partial t} = \boldsymbol{r}(t, \boldsymbol{q}),\]

where \(\boldsymbol{q}=[q_1,q_2,\ldots]\) is the vector of state variables and \(\boldsymbol{r}=[r_1,r_2,\ldots]\) is the vector of right-hand side functions. The classes in this module have a single_step(q, t, h, r, ...) method that steps from time level \(t^n\) to the next time, \(t^{n+1}=t^n + h\), given a state \(q^n\) and right-hand side function \(r(t,q)\). For example, the forward Euler method with class ForwardEuler computes this as \(q^{n+1}=q^n + hr(t^n,q^n)\).

In Spitfire’s unit testing we verify the order of accuracy of most of these methods. If you add a new one be sure to add it to the unit tester. See the file: tests/time/test_time_order_of_accuracy.py.

class spitfire.time.methods.BackwardEulerS1P1Q1(nonlinear_solver, norm_weighting=1.0, norm_order=inf)¶

Bases: TimeStepperBase

Constructor:

Parameters:

nonlinear_solverspitfire.time.nonlinear.NonlinearSolver: the solver used in each implicit stage
norm_weightingfloat or np.ndarray the size of the state vector: multiplies the embedded error estimate prior to computing the norm (default: 1.)
norm_orderint or np.inf: order of the norm of the error estimate (default: np.inf)

implicit_coefficient¶

is_adaptive¶

is_implicit¶

n_stages¶

name¶

nonlinear_solver¶

norm_order¶

norm_weighting¶

order¶

single_step(state, t, dt, rhs, lhs_setup, lhs_solve, *args, **kwargs)¶

class spitfire.time.methods.BogackiShampineS4P3Q2(norm_weighting=1.0, norm_order=inf)¶

Bases: TimeStepperBase

Constructor:

Parameters:

norm_weightingfloat or np.ndarray the size of the state vector: multiplies the embedded error estimate prior to computing the norm (default: 1.)
norm_orderint or np.inf: order of the norm of the error estimate (default: np.inf)

implicit_coefficient¶

is_adaptive¶

is_implicit¶

n_stages¶

name¶

nonlinear_solver¶

norm_order¶

norm_weighting¶

order¶

single_step(state, t, dt, rhs, *args, **kwargs)¶

class spitfire.time.methods.CashKarpS6P5Q4(norm_weighting=1.0, norm_order=inf)¶

Bases: TimeStepperBase

Constructor:

Parameters:

norm_weightingfloat or np.ndarray the size of the state vector: multiplies the embedded error estimate prior to computing the norm (default: 1.)
norm_orderint or np.inf: order of the norm of the error estimate (default: np.inf)

implicit_coefficient¶

is_adaptive¶

is_implicit¶

n_stages¶

name¶

nonlinear_solver¶

norm_order¶

norm_weighting¶

order¶

single_step(state, t, dt, rhs, *args, **kwargs)¶

class spitfire.time.methods.CrankNicolsonS2P2(nonlinear_solver)¶

Bases: TimeStepperBase

Constructor:

Parameters:

nonlinear_solverspitfire.time.nonlinear.NonlinearSolver: the solver used in each implicit stage

implicit_coefficient¶

is_adaptive¶

is_implicit¶

n_stages¶

name¶

nonlinear_solver¶

norm_order¶

norm_weighting¶

order¶

single_step(state, t, dt, rhs, lhs_setup, lhs_solve, *args, **kwargs)¶

class spitfire.time.methods.ExpKennedyCarpetnerS6P4Q3(norm_weighting=1.0, norm_order=inf)¶

Bases: TimeStepperBase

Constructor:

Parameters:

norm_weightingfloat or np.ndarray the size of the state vector: multiplies the embedded error estimate prior to computing the norm (default: 1.)
norm_orderint or np.inf: order of the norm of the error estimate (default: np.inf)

implicit_coefficient¶

is_adaptive¶

is_implicit¶

n_stages¶

name¶

nonlinear_solver¶

norm_order¶

norm_weighting¶

order¶

single_step(state, t, dt, rhs, *args, **kwargs)¶

class spitfire.time.methods.ExpMidpointS2P2¶

Bases: TimeStepperBase

implicit_coefficient¶

is_adaptive¶

is_implicit¶

n_stages¶

name¶

nonlinear_solver¶

norm_order¶

norm_weighting¶

order¶

single_step(state, t, dt, rhs, *args, **kwargs)¶

class spitfire.time.methods.ExpRalstonS2P2¶

Bases: TimeStepperBase

implicit_coefficient¶

is_adaptive¶

is_implicit¶

n_stages¶

name¶

nonlinear_solver¶

norm_order¶

norm_weighting¶

order¶

single_step(state, t, dt, rhs, *args, **kwargs)¶

class spitfire.time.methods.ExpTrapezoidalS2P2Q1(norm_weighting=1.0, norm_order=inf)¶

Bases: TimeStepperBase

Constructor:

Parameters:

norm_weightingfloat or np.ndarray the size of the state vector: multiplies the embedded error estimate prior to computing the norm (default: 1.)
norm_orderint or np.inf: order of the norm of the error estimate (default: np.inf)

implicit_coefficient¶

is_adaptive¶

is_implicit¶

n_stages¶

name¶

nonlinear_solver¶

norm_order¶

norm_weighting¶

order¶

single_step(state, t, dt, rhs, *args, **kwargs)¶

class spitfire.time.methods.ForwardEulerS1P1¶

Bases: TimeStepperBase

implicit_coefficient¶

is_adaptive¶

is_implicit¶

n_stages¶

name¶

nonlinear_solver¶

norm_order¶

norm_weighting¶

order¶

single_step(state, t, dt, rhs, *args, **kwargs)¶

class spitfire.time.methods.GeneralAdaptiveERK(name, order, A, b, bhat=None, norm_weighting=1.0, norm_order=inf)¶

Bases: TimeStepperBase

A general-purpose explicit Runge-Kutta method with embedded error estimation for adaptive time stepping

Constructor:

Parameters:

namestr: name of the TimeStepper, e.g. ‘Forward Euler’ or ‘Runge Kutta 4’
orderint: order of accuracy of the time stepping method
Anp.ndarray: Runge-Kutta stage coefficients for the method
bnp.ndarray: quadrature coefficients for the method
bhatnp.ndarray: embedded error estimation quadrature coefficients (default: None - not adaptive)
norm_weightingfloat or np.ndarray the size of the state vector: multiplies the embedded error estimate prior to computing the norm (default: 1.)
norm_orderint or np.inf: order of the norm of the error estimate (default: np.inf)

implicit_coefficient¶

is_adaptive¶

is_implicit¶

n_stages¶

name¶

nonlinear_solver¶

norm_order¶

norm_weighting¶

order¶

single_step(state, t, dt, rhs, *args, **kwargs)¶

class spitfire.time.methods.GeneralAdaptiveERKMultipleEmbedded(name, order, A, b, bhats, norm_weighting=1.0, norm_order=inf)¶

Bases: TimeStepperBase

A general-purpose explicit Runge-Kutta method with embedded error estimation for adaptive time stepping

This class is used for advanced adaptive methods that utilize multiple embedded error estimates.

Constructor:

Parameters:

namestr: name of the TimeStepper, e.g. ‘Forward Euler’ or ‘Runge Kutta 4’
orderint: order of accuracy of the time stepping method
Anp.ndarray: Runge-Kutta stage coefficients for the method
bnp.ndarray: quadrature coefficients for the method
bhatslist[np.ndarray]: list of embedded error estimation quadrature coefficients
norm_weightingfloat or np.ndarray the size of the state vector: multiplies the embedded error estimate prior to computing the norm (default: 1.)
norm_orderint or np.inf: order of the norm of the error estimate (default: np.inf)

implicit_coefficient¶

is_adaptive¶

is_implicit¶

n_stages¶

name¶

nonlinear_solver¶

norm_order¶

norm_weighting¶

order¶

single_step(state, t, dt, rhs, *args, **kwargs)¶

class spitfire.time.methods.KennedyCarpenterS4P3Q2(nonlinear_solver, norm_weighting=1.0, norm_order=inf)¶

Bases: TimeStepperBase

Constructor:

Parameters:

nonlinear_solverspitfire.time.nonlinear.NonlinearSolver: the solver used in each implicit stage
norm_weightingfloat or np.ndarray the size of the state vector: multiplies the embedded error estimate prior to computing the norm (default: 1.)
norm_orderint or np.inf: order of the norm of the error estimate (default: np.inf)

A¶

a21¶

a31¶

a32¶

a41¶

a42¶

a43¶

b1¶

b1h¶

b2¶

b2h¶

b3¶

b3h¶

b4¶

b4h¶

c¶

gamma¶

single_step(state, t, dt, rhs, lhs_setup, lhs_solve, *args, **kwargs)¶

class spitfire.time.methods.KennedyCarpenterS6P4Q3(nonlinear_solver, norm_weighting=1.0, norm_order=inf)¶

Bases: TimeStepperBase

Constructor:

Parameters:

nonlinear_solverspitfire.time.nonlinear.NonlinearSolver: the solver used in each implicit stage
norm_weightingfloat or np.ndarray the size of the state vector: multiplies the embedded error estimate prior to computing the norm (default: 1.)
norm_orderint or np.inf: order of the norm of the error estimate (default: np.inf)

A¶

a21¶

a31¶

a32¶

a41¶

a42¶

a43¶

a51¶

a52¶

a53¶

a54¶

a61¶

a62¶

a63¶

a64¶

a65¶

b1¶

b1h¶

b2¶

b2h¶

b3¶

b3h¶

b4¶

b4h¶

b5¶

b5h¶

b6¶

b6h¶

c¶

gamma¶

single_step(state, t, dt, rhs, lhs_setup, lhs_solve, *args, **kwargs)¶

class spitfire.time.methods.KennedyCarpenterS8P5Q4(nonlinear_solver, norm_weighting=1.0, norm_order=inf)¶

Bases: TimeStepperBase

Constructor:

Parameters:

nonlinear_solverspitfire.time.nonlinear.NonlinearSolver: the solver used in each implicit stage
norm_weightingfloat or np.ndarray the size of the state vector: multiplies the embedded error estimate prior to computing the norm (default: 1.)
norm_orderint or np.inf: order of the norm of the error estimate (default: np.inf)

A¶

a21¶

a31¶

a32¶

a41¶

a42¶

a43¶

a51¶

a52¶

a53¶

a54¶

a61¶

a62¶

a63¶

a64¶

a65¶

a71¶

a72¶

a73¶

a74¶

a75¶

a76¶

a81¶

a82¶

a83¶

a84¶

a85¶

a86¶

a87¶

b1¶

b1h¶

b2¶

b2h¶

b3¶

b3h¶

b4¶

b4h¶

b5¶

b5h¶

b6¶

b6h¶

b7¶

b7h¶

b8¶

b8h¶

c¶

gamma¶

single_step(state, t, dt, rhs, lhs_setup, lhs_solve, *args, **kwargs)¶

class spitfire.time.methods.KvaernoS4P3Q2(nonlinear_solver, norm_weighting=1.0, norm_order=inf)¶

Bases: TimeStepperBase

Constructor:

Parameters:

nonlinear_solverspitfire.time.nonlinear.NonlinearSolver: the solver used in each implicit stage
norm_weightingfloat or np.ndarray the size of the state vector: multiplies the embedded error estimate prior to computing the norm (default: 1.)
norm_orderint or np.inf: order of the norm of the error estimate (default: np.inf)

A¶

a21¶

a31¶

a32¶

a41¶

a42¶

a43¶

b1¶

b1h¶

b2¶

b2h¶

b3¶

b3h¶

b4¶

b4h¶

c¶

gamma¶

single_step(state, t, dt, rhs, lhs_setup, lhs_solve, *args, **kwargs)¶

class spitfire.time.methods.RK3KuttaS3P3¶

Bases: TimeStepperBase

implicit_coefficient¶

is_adaptive¶

is_implicit¶

n_stages¶

name¶

nonlinear_solver¶

norm_order¶

norm_weighting¶

order¶

single_step(state, t, dt, rhs, *args, **kwargs)¶

class spitfire.time.methods.RK4ClassicalS4P4¶

Bases: TimeStepperBase

implicit_coefficient¶

is_adaptive¶

is_implicit¶

n_stages¶

name¶

nonlinear_solver¶

norm_order¶

norm_weighting¶

order¶

single_step(state, t, dt, rhs, *args, **kwargs)¶

class spitfire.time.methods.StepOutput(**kwargs)¶

Bases: object

Read-only class that holds information about the result of a single time step.

Constructor: build a StepOutput object, specifying all data here (the object will be read-only)

Parameters:

solution_updatenp.ndarray: the update to the solution, the state at the next time level minus that at the current time level
temporal_errorfloat: the temporal error estimate - for adaptive time stepping through classical error control
nonlinear_iterint: how many nonlinear iterations the step required - implicit methods only
linear_iterint: how many linear iterations the step required - implicit methods only
nonlinear_convergedbool: whether or not the nonlinear solver converged - implicit methods only
slow_nonlinear_convergencebool: whether or not the nonlinear solver detected slow convergence - implicit methods only
projector_setupsint: the number of times the linear system was set up (e.g. Jacobian evaluation-factorization)
extra_errorslist[float]: a list of additional embedded temporal error estimates - for adaptive time stepping through new ratio control

extra_errors¶

linear_iter¶

nonlinear_converged¶

nonlinear_iter¶

projector_setups¶

slow_nonlinear_convergence¶

solution_update¶

temporal_error¶

class spitfire.time.methods.TimeStepperBase(name, order, **kwargs)¶

Bases: object

Read-only base class for all time stepping methods

Constructor: build a StepOutput object, specifying all data here (the object will be read-only)

Parameters:

namestr: the name of the method
orderint: the order of the method
is_adaptivebool: whether or not the method computes embedded error estimates to enable adaptive time-stepping
norm_weightingfloat or np.ndarray the size of the state vector: multiplies the embedded error estimate prior to computing the norm (default: 1.)
norm_orderint or np.inf: order of the norm of the error estimate (default: np.inf)
is_implicitbool: whether or not the method is implicit
nonlinear_solverint: the nonlinear solver used by an implicit method at each time step
implicit_coefficientlist[float]: the coefficient in the implicit method that pre-multiplies the Jacobian matrix in the linear system

implicit_coefficient¶

is_adaptive¶

is_implicit¶

n_stages¶

name¶

nonlinear_solver¶

norm(x)¶

norm_order¶

norm_weighting¶

order¶

class spitfire.time.methods.ZonneveldS5P4Q3(norm_weighting=1.0, norm_order=inf)¶

Bases: TimeStepperBase

Constructor:

Parameters:

norm_weightingfloat or np.ndarray the size of the state vector: multiplies the embedded error estimate prior to computing the norm (default: 1.)
norm_orderint or np.inf: order of the norm of the error estimate (default: np.inf)

implicit_coefficient¶

is_adaptive¶

is_implicit¶

n_stages¶

name¶

nonlinear_solver¶

norm_order¶

norm_weighting¶

order¶

single_step(state, t, dt, rhs, *args, **kwargs)¶

5.1.1.4.4. spitfire.time.nonlinear module¶

This module contains nonlinear solvers used in time stepping. At the moment this is simply Newton’s method.

class spitfire.time.nonlinear.NonlinearSolver(*args, **kwargs)¶

Bases: object

Base class for nonlinear solvers.

Constructor: build a NonlinearSolver object

Parameters:

max_nonlinear_iterint: maximum number of nonlinear iterations to try (default: 20)
slowness_detection_iterint: how many iterations the solver runs can run without declaring convergence “slow” (default: Inf)
must_convergebool: whether or not the solver must converge to a solution within max_nonlinear_iter (default: False)
norm_weightingnp.ndarray or float: how the temporal error estimate is weighted in its norm calculation (default: 1)
norm_orderint or np.inf: the order of the norm used in the temporal error estimate (default: Inf)
raise_naninfbool: whether or not to check for NaN/Inf values in the solution and residual and raise an exception if found (default: False)
custom_solution_checkcallable: a function of the solution that executes custom checks for solution validity (default: None)
setup_projector_in_governorbool: whether or not the linear projector is set up outside of the solver (default: True)

defaults = {'custom_solution_check': None, 'max_nonlinear_iter': 20, 'must_converge': False, 'norm_order': inf, 'norm_weighting': 1.0, 'raise_naninf': False, 'setup_projector_in_governor': True, 'slowness_detection_iter': inf, 'tolerance': 1e-12}¶

class spitfire.time.nonlinear.SimpleNewtonSolver(evaluate_jacobian_every_iter=False, *args, **kwargs)¶

Bases: NonlinearSolver

Simple Newton solver

Constructor: build a SimpleNewtonSolver object

Parameters:

evaluate_jacobian_every_iterbool: whether or not to set up the linear projector on every iteration of Newton’s method (default: False)
max_nonlinear_iterint: maximum number of nonlinear iterations to try (default: 20)
slowness_detection_iterint: how many iterations the solver runs can run without declaring convergence “slow” (default: Inf)
must_convergebool: whether or not the solver must converge to a solution within max_nonlinear_iter (default: False)
norm_weightingnp.ndarray or float: how the temporal error estimate is weighted in its norm calculation (default: 1)
norm_orderint or np.inf: the order of the norm used in the temporal error estimate (default: Inf)
raise_naninfbool: whether or not to check for NaN/Inf values in the solution and residual and raise an exception if found (default: False)
custom_solution_checkcallable: a function of the solution that executes custom checks for solution validity (default: None)
setup_projector_in_governorbool: whether or not the linear projector is set up outside of the solver (default: True)

property evaluate_jacobian_every_iter¶

class spitfire.time.nonlinear.SolverOutput(**kwargs)¶

Bases: object

Read-only class that holds information about the result of a nonlinear solver.

Constructor: build a SolverOutput object, specifying all data here (the object will be read-only)

Parameters:

solutionnp.ndarray: the solution to the nonlinear system
iterint: how many nonlinear iterations were needed for convergence
literint: how many total linear iterations were needed for convergence
convergedbool: whether or not the solver converged to a solution
slow_convergencebool: whether or not the solver detected slow convergence
projector_setupsint: the number of times the linear projector was set up (e.g. Jacobian evaluation-factorization)
rhs_at_convergednp.ndarray: the right-hand side of the ODE system at the converged solution

converged¶

iter¶

liter¶

projector_setups¶

rhs_at_converged¶

slow_convergence¶

solution¶

spitfire.time.nonlinear.finite_difference_jacobian(residual_func, residual_value, state, offset_rel=1e-05, offset_abs=1e-08)¶

Compute a simple one-sided finite difference approximation to the Jacobian of a residual function.

Parameters:

residual_funccallable f(q)->r: residual function of the state vector, r(q)
residual_valuenp.array: value of the residual function at the specified state vector
statenp.array: the state vector
offset_relfloat: the relative contribution to the finite difference delta (optional, default: 1e-5)
offset_absfloat: the absolute contribution to the finite difference delta (optional, default: 1e-8)
Returns
——-
jnp.ndarray: the approximate Jacobian matrix

5.1.1.4.5. spitfire.time.stepcontrol module¶

This module contains controllers for adaptive time stepping based on embedded temporal error estimation.

class spitfire.time.stepcontrol.CascadeController(kp=0.06666666667, ki=0.1333333333, ratio_kp=0.1, ratio_ki=0.3, initial_target_error=1e-10, target_ratio=0.01, max_step=0.001, max_ramp=1.1, first_step=1e-06)¶

Bases: object

A two-level cascade control system on the embedded temporal error estimate and the ratio of two estimates.

The stepper method must support multiple embedded error estimates.

Constructor:

Parameters:

kpfloat: the modal gain of the proportional control mode for the error controller (default: 0.06666666667)
kifloat: the modal gain of the integral control mode for the error controller (default: 0.1333333333)
ratio_kpfloat: the modal gain of the proportional control mode for the ratio controller (default: 0.1)
ratio_kifloat: the modal gain of the integral control mode for the ratio controller (default: 0.3)
target_ratiofloat: the value of the target ratio for the controller (default: 1.e-2)
initial_target_errorfloat: the initial value of the target error for the controller (default: 1.e-10)
max_stepfloat: the maximum allowable time step (default: 1.e-3)
max_rampfloat: the maximum allowable rate of increase of the time step (default: 1.1)
first_stepfloat: the initial step size (default: 1.e-6)

first_step_size()¶: Obtain the initial step size

last_step_size()¶: Obtain the most recent step size

step_size_is_constant()¶: Whether or not this controller has a constant or variable step size

target_error()¶: Obtain the most target error, needed here just to avoid a base class

class spitfire.time.stepcontrol.ConstantTimeStep(step_size)¶

Bases: object

A simple wrapper class for a constant time step.

Constructor:

Parameters:

step_sizefloat: the size of the time step

first_step_size()¶: Obtain the initial step size

last_step_size()¶: Obtain the most recent step size

step_size_is_constant()¶: Whether or not this controller has a constant or variable step size

target_error()¶: Obtain the most target error, needed here just to avoid a base class

class spitfire.time.stepcontrol.PIController(kp=0.06666666667, ki=0.1333333333, target_error=0.0001, max_step=10000.0, max_ramp=1.1, first_step=0.001)¶

Bases: object

A PI controller on the embedded temporal error estimate

Constructor:

Parameters:

kpfloat: the modal gain of the proportional control mode (default: 0.06666666667)
kifloat: the modal gain of the integral control mode (default: 0.1333333333)
target_errorfloat: the target error for the controller (default: 1.e-10)
max_stepfloat: the maximum allowable time step (default: 1.e-3)
max_rampfloat: the maximum allowable rate of increase of the time step (default: 1.1)
first_stepfloat: the initial step size (default: 1.e-6)

first_step_size()¶: Obtain the initial step size

last_step_size()¶: Obtain the most recent step size

step_size_is_constant()¶: Whether or not this controller has a constant or variable step size

target_error()¶: Obtain the most target error, needed here just to avoid a base class

class spitfire.time.stepcontrol.RatioController(kp=0.1, ki=0.3, target_ratio=0.01, max_step=0.001, max_ramp=1.1, first_step=1e-06)¶

Bases: object

A PI controller on the ratio of two embedded temporal error estimates

The stepper method must support multiple embedded error estimates.

Constructor:

Parameters:

kpfloat: the modal gain of the proportional control mode (default: 0.1)
kifloat: the modal gain of the integral control mode (default: 0.3)
target_ratiofloat: the target error ratio for the controller (default: 1.e-2)
max_stepfloat: the maximum allowable time step (default: 1.e-3)
max_rampfloat: the maximum allowable rate of increase of the time step (default: 1.1)
first_stepfloat: the initial step size (default: 1.e-6)

first_step_size()¶: Obtain the initial step size

last_step_size()¶: Obtain the most recent step size

step_size_is_constant()¶: Whether or not this controller has a constant or variable step size

target_error()¶: Obtain the most target error, needed here just to avoid a base class

5.1.1.4.6. Module contents¶

This module contains Spitfire’s core time integration methods.