desolver package

Subpackages

• desolver.exception_types package
  • Submodules
  • desolver.exception_types.exception_types module
    • FailedIntegration
    • FailedToMeetTolerances
    • RecursionError
  • Module contents
• desolver.integrators package
  • Submodules
  • desolver.integrators.integration_schemes module
  • desolver.integrators.integrator_template module
    • IntegratorTemplate
      • IntegratorTemplate.adaptation_fn
      • IntegratorTemplate.dense_output()
      • IntegratorTemplate.get_error_estimate()
      • IntegratorTemplate.is_adaptive
      • IntegratorTemplate.order
      • IntegratorTemplate.symplectic
      • IntegratorTemplate.update_timestep()
    • RichardsonIntegratorTemplate
      • RichardsonIntegratorTemplate.adaptive
      • RichardsonIntegratorTemplate.symplectic
  • desolver.integrators.integrator_types module
    • ExplicitSymplecticIntegrator
      • ExplicitSymplecticIntegrator.tableau
      • ExplicitSymplecticIntegrator.symplectic
      • ExplicitSymplecticIntegrator.dense_output()
      • ExplicitSymplecticIntegrator.step()
      • ExplicitSymplecticIntegrator.symplectic
    • RungeKuttaIntegrator
      • RungeKuttaIntegrator.algebraic_system()
      • RungeKuttaIntegrator.algebraic_system_jacobian()
      • RungeKuttaIntegrator.get_error_estimate()
      • RungeKuttaIntegrator.step()
      • RungeKuttaIntegrator.tableau_final
    • generate_richardson_integrator()
  • Module contents
    • available_methods()
    • explicit_methods()
    • implicit_methods()
• desolver.utilities package
  • Submodules
  • desolver.utilities.interpolation module
    • CubicHermiteInterp
      • CubicHermiteInterp.grad()
      • CubicHermiteInterp.trange
      • CubicHermiteInterp.tshift
  • desolver.utilities.optimizer module
    • brentsroot()
    • brentsrootvec()
    • newtontrustregion()
    • nonlinear_roots()
    • transform_to_bounded_fn()
    • transform_to_bounded_jac()
    • transform_to_bounded_x()
    • transform_to_unbounded_x()
  • desolver.utilities.utilities module
    • BlockTimer
      • BlockTimer.elapsed()
      • BlockTimer.end()
      • BlockTimer.restart_timer()
      • BlockTimer.start()
    • JacobianWrapper
      • JacobianWrapper.rhs
      • JacobianWrapper.base_order
      • JacobianWrapper.richardson_iter
      • JacobianWrapper.order
      • JacobianWrapper.adaptive
      • JacobianWrapper.flat
      • JacobianWrapper.adaptive_richardson()
      • JacobianWrapper.check_converged()
      • JacobianWrapper.estimate()
      • JacobianWrapper.richardson()
    • convert_suffix()
    • search_bisection()
    • search_bisection_vec()
    • warning()
  • Module contents

Submodules

desolver.differential_system module

class desolver.differential_system.DiffRHS(rhs, sample_input=None, equ_repr=None, md_repr=None)

Bases: object

Differential Equation class. Designed to wrap around around a function for the right-hand side of an ordinary differential equation.

rhs

Right-hand side of an ordinary differential equation

Type:

callable

equ_repr

String representation of the right-hand side.

Type:

str

hook_jacobian_call(jac_fn)

Attaches a function, jac_fn, that returns the jacobian of self.rhs as an array with shape (state.numel(), rhs.numel()).

jac(t, y, *args, **kwargs)

Returns the jacobian of self.rhs at a given time (t) and state (y). Tracks number of jacobian evaluations.

Uses a Richardson Extrapolated 5th order central finite differencing method when a jacobian is not defined as self.rhs.jac or by self.hook_jacobian_call

property jac_is_wrapped_rhs

set_jac_base_order(order)

unhook_jacobian_call()

Detaches the current jacobian function. On next call to jac this will be reinitialised to either a finite difference estimate or a pytorch jacrev functional transform

class desolver.differential_system.OdeSystem(equ_rhs, y0, t=(0, 1), dense_output=False, dt=1.0, rtol=None, atol=None, constants={})

Bases: object

Ordinary Differential Equation class. Designed to be used with a system of ordinary differential equations.

property atol

The absolute tolerance of the adaptive integration schemes

property constants

A dictionary of constants for the differential system.

property dt

The timestep of the numerical integration

property events

A tuple of (time, state, event) tuples containing the times and states for each event that triggered

Examples

>>> ode_system = desolver.OdeSystem(...)
>>> ode_system.integrate(events=[...])
>>> ode_system.events
(StateTuple(t=..., y=..., event=event_1), StateTuple(t=..., y=..., event=event_2), etc.)

property events_dict

A tuple of (time, state, event) tuples containing the times and states for each event that triggered

Examples

>>> ode_system = desolver.OdeSystem(...)
>>> ode_system.integrate(events=[...])
>>> ode_system.events
(StateTuple(t=..., y=..., event=event_1), StateTuple(t=..., y=..., event=event_2), etc.)

get_current_time()

Returns the current time of the ODE system

get_step_interpolant()

initialise_integrator(preserve_states=False)

integrate(t=None, callback=None, eta=False, events=None)

Integrates the system to a specified time.

Parameters:

• t (float) – If t is specified, then the system will be integrated to time t. Otherwise the system will integrate to the specified final time. NOTE: t can be negative in order to integrate backwards in time, but use this with caution as this functionality is slightly unstable.

• callback (callable or list of callables) – A callable object or list of callable objects that are invoked as callback(self) at each time step. e.g. for logging integration to disk, saving data, manipulating the state of the system, etc.

• eta (bool) – Specifies whether or not the integration process should return an eta, current progress and simple information regarding step-size and current time. Will be deprecated in the future in favour of verbosity argument that prints once every n-steps. NOTE: This may slow the integration process down as the process of outputting these values create overhead.

• events (callable or list of callables) –

  Events to track, defaults to None. Each function must have the signature event(t, y, **kwargs) and the solver will find the time t such that event(t, y, **kwargs) == 0. The **kwargs argument allows the solver to pass the system constants to the function. Additionally, each event function can possess the following two attributes:

  direction: bool, optional

  Indicates the direction of the event crossing that will register an event.

  is_terminal: bool, optional

  Indicates whether the detection of the event terminates the numerical integration.

Raises:

RecursionError : – Raised if an adaptive integrator recurses beyond the recursion limit when attempting to compute a forward step. This usually means that the numerical integration did not converge and that the behaviour of the system is highly unreliable. This could be due to numerical issues.

property integration_status

Returns the integration status as a human-readable string.

Returns:

String containing the integration status message.

Return type:

str

property method

The numerical integration scheme

property nfev

The number of function evaluations used during the numerical integration

property njev

The number of jacobian evaluations used during the numerical integration

reset()

Resets the system to the initial time.

property rtol

The relative tolerance of the adaptive integration schemes

set_kick_vars(staggered_mask)

Sets the variable mask for the symplectic integrators.

The conventional structure of a symplectic integrator is Kick-Drift-Kick or Drift-Kick-Drift where Drift is when the Positions are updated and Kick is when the Velocities are updated.

The default assumption is that the latter half of the variables are to be updated in the Kick step and the former half in the Drift step.

Does nothing if integrator is not symplectic.

Parameters:

staggered_mask (array of bools) – A boolean array with the same shape as y. Specifies the elements of y that are to be updated as part of the Kick step.

set_method(new_method, staggered_mask=None, preserve_states=True)

Sets the method of integration.

Parameters:

• new_method (str or stateful functor) – A string that is the name of an integrator that is available in DESolver, OR a functor that takes the current time, state, time step and equation, and advances the state by 1 timestep adjusting the timestep as necessary.

• staggered_mask (boolean masking array) – A boolean array with the same shape as the system state that indicates which variables are updated during the ‘kick’ stage of a symplectic integrator. Has no effect if the integrator is adaptive.

Raises:

ValueError – If the string is not a valid integration scheme.

property sol

property success

property t

The times at which the system has been evaluated.

property t0

The initial integration time

property tf

The final integration time

property y

The states at which the system has been evaluated.

desolver.differential_system.rhs_prettifier(equ_repr=None, md_repr=None)

desolver.differential_system.solve_ivp(fun, t_span, y0, method='RK45', t_eval=None, dense_output=False, events=None, vectorized=False, args=None, **options)

Drop-in replacement for scipy.integrate.solve_ivp, provides a functional interface to the desolver integration routines.

Module contents