rk_class – rklib

type, public, abstract :: rk_class

main integration class

Inherits

Help

Components

Type	Visibility	Attributes		Name		Initial
integer,	private		::	istatus	=	0	status code
logical,	private		::	stopped	=	.false.	if user has stopped the integration in `f` or `report`.
integer,	private		::	num_steps	=	0	number of accepted steps taken
integer,	private		::	max_number_of_steps	=	huge(1)	maximum number of steps to take
integer,	private		::	report_rate	=	1	how often to call report function: `0` : no reporting (same as not associating `report`), `1` : report every point, `2` : report every other point, etc. The first and last point are always reported.
logical,	private		::	stop_on_errors	=	.false.	if true, then errors will stop the program
integer,	private		::	n	=	0	user specified number of variables
procedure(deriv_func),	private,	pointer	::	f	=>	null()	user-specified derivative function
procedure(report_func),	private,	pointer	::	report	=>	null()	user-specified report function
procedure(event_func),	private,	pointer	::	g	=>	null()	event function (stop when this is zero)
type(root_method),	private		::	solver	=	root_method_brent	the root solver method to use for even finding
real(kind=wp),	private,	dimension(:,:), allocatable	::	funcs			matrix to store the function evaluations in the step function. this will be size (`n` x `number_of_registers`). If the dense output is enabled, and the method needs extra function evaluations for it (see dense_extra_stages), these are stored in additional columns after the ones for the step, so the size is (`n` x the number of rows of `dense_b`).
logical,	private		::	dense_enabled	=	.false.	if the dense output was enabled by the user (see initialize_variable_step)
integer,	private		::	dense_form	=	0	the form of the `dense_b` coefficients (`dense_form_polynomial` or `dense_form_dopri`)
real(kind=wp),	private,	dimension(:,:), allocatable	::	dense_b			dense output coefficients (allocated if the method has a dense output, even if it is not enabled) (`number_of_stages` x `degree`). See dense_coefficients.
logical,	private		::	dense_available	=	.false.	if the dense output data for the last step is valid
logical,	private		::	dense_computed	=	.false.	if `dense_r` has been computed for the last step
logical,	private		::	dense_computing	=	.false.	if `dense_r` is being computed (to detect recursive calls to interpolate from `f`)
real(kind=wp),	private		::	dense_t	=	zero	initial time of the last accepted step
real(kind=wp),	private		::	dense_h	=	zero	size of the last accepted step
real(kind=wp),	private,	dimension(:), allocatable	::	dense_x			initial state of the last accepted step (`n`)
real(kind=wp),	private,	dimension(:), allocatable	::	dense_xf			final state of the last accepted step (`n`)
real(kind=wp),	private,	dimension(:,:), allocatable	::	dense_r			interpolating polynomial coefficients for the last accepted step (`n` x `degree`)

Type-Bound Procedures

procedure, public :: destroy

destructor

private subroutine destroy(me)

Destructor for rk_class.

Arguments

Type	Intent	Optional	Attributes		Name
class(rk_class),	intent(out)			::	me

procedure, public :: stop => rk_class_stop

user-callable method to stop the integration

private subroutine rk_class_stop(me)

User-callable method to stop the integration (e.g., from f, g, or report). No further function evaluations are done, and the integrator returns, with the status set to RKLIB_ERROR_USER_STOPPED. This is not treated as an error (i.e., it does not stop the program if stop_on_errors is true).

Arguments

Type	Intent	Optional	Attributes		Name
class(rk_class),	intent(inout)			::	me

procedure, public :: status => rk_class_status

get status code and message

private subroutine rk_class_status(me, istatus, message)

Get the status of an integration.

Arguments

Type	Intent	Optional	Attributes		Name
class(rk_class),	intent(in)			::	me
integer,	intent(out),	optional		::	istatus	status code (`<0` means an error)
character(len=:),	intent(out),	optional,	allocatable	::	message	status message

procedure, public :: failed

private function failed(me)

Returns true if there was an error. Can use rk_class_status to get more info.

Arguments

Type	Intent	Optional	Attributes		Name
class(rk_class),	intent(in)			::	me

Return Value logical

procedure, public :: interpolate

dense output for the last accepted step

private recursive subroutine interpolate(me, t, x, istatus)

Dense output: compute the state at a time within the last accepted step, using the continuous extension of the method (if it has one, see rklib_properties dense).

Arguments

Type	Intent	Optional	Attributes		Name
class(rk_class),	intent(inout)			::	me
real(kind=wp),	intent(in)			::	t	time at which to compute the state
real(kind=wp),	intent(out),		dimension(me%n)	::	x	state at `t`
integer,	intent(out),	optional		::	istatus	status of this call

procedure, public :: dense_interval

interval of the last accepted step for the dense output

private subroutine dense_interval(me, available, t0, tf, x0, xf)

Returns the interval of the last accepted step, which is where interpolate can be used. For example, this can be called from the report function to get the previous time and state, so that points in between can be computed.

Arguments

Type	Intent	Optional	Attributes		Name
class(rk_class),	intent(inout)			::	me
logical,	intent(out)			::	available	if dense output is available
real(kind=wp),	intent(out),	optional		::	t0	initial time of the step
real(kind=wp),	intent(out),	optional		::	tf	final time of the step
real(kind=wp),	intent(out),	optional,	dimension(me%n)	::	x0	initial state of the step
real(kind=wp),	intent(out),	optional,	dimension(me%n)	::	xf	final state of the step

procedure, private :: init => initialize_rk_class

private subroutine initialize_rk_class(me, n, f, report, g, stop_on_errors, max_number_of_steps, report_rate, solver, dense_output)

Initialize the rk_class.

Arguments

Type	Intent	Optional		Name
class(rk_class),	intent(inout)		::	me
integer,	intent(in)		::	n	number of variables
procedure(deriv_func)			::	f	derivative function
procedure(report_func),		optional	::	report	for reporting the steps
procedure(event_func),		optional	::	g	for stopping at an event
logical,	intent(in),	optional	::	stop_on_errors	stop the program for any errors (default is False)
integer,	intent(in),	optional	::	max_number_of_steps	max number of steps allowed
integer,	intent(in),	optional	::	report_rate	how often to call report function: `0` : no reporting (same as not associating `report`), `1` : report every point, `2` : report every other point, etc. The first and last point are always reported.
class(root_method),	intent(in),	optional	::	solver	the root-finding method to use for even finding. if not present, then `brent_solver` is used.
logical,	intent(in),	optional	::	dense_output	to enable the dense output (default is False). This is ignored if the method does not have one.

procedure, private :: begin => begin_integration_rk_class

private subroutine begin_integration_rk_class(me)

Begin an integration.

Arguments

Type	Intent	Optional	Attributes		Name
class(rk_class),	intent(inout)			::	me

procedure, private :: raise_exception

private subroutine raise_exception(me, error_code)

Raise an exception.

Arguments

Type	Intent	Optional	Attributes		Name
class(rk_class),	intent(inout)			::	me
integer,	intent(in)			::	error_code	the error to raise

procedure, private :: clear_exception

private subroutine clear_exception(me)

Clear any exception.

Arguments

Type	Intent	Optional	Attributes		Name
class(rk_class),	intent(inout)			::	me

procedure, private :: export_point

private subroutine export_point(me, t, x, first_or_last)

Wrapper for exporting points during integration.

Arguments

Type	Intent	Optional	Attributes		Name
class(rk_class),	intent(inout)			::	me
real(kind=wp),	intent(in)			::	t
real(kind=wp),	intent(in),		dimension(:)	::	x
logical,	intent(in),	optional		::	first_or_last	if this is the first or last point (always reported)

procedure, private :: dense_coefficients

dense output coefficients for the method

private pure subroutine dense_coefficients(me, b, form)

Returns the dense output coefficients for the method. This is the default for methods that do not have a dense output (b is not allocated).

Arguments

Type	Intent	Attributes		Name
class(rk_class),	intent(in)		::	me
real(kind=wp),	intent(out),	dimension(:,:), allocatable	::	b	dense output coefficients
integer,	intent(out)		::	form	the form of `b` (`dense_form_polynomial` or `dense_form_dopri`)

procedure, private :: dense_extra_stages

additional function evaluations for the dense output

private subroutine dense_extra_stages(me)

Compute any additional function evaluations needed for the dense output of the last accepted step, and store them in me%funcs (after the ones used by the step function). This is the default for methods that don't need any.

Arguments

Type	Intent	Optional	Attributes		Name
class(rk_class),	intent(inout)			::	me

procedure, private :: dense_save

private subroutine dense_save(me, t, x, h, xf)

Save the data needed for the dense output of a step that was just accepted. The function evaluations of the step are taken from me%funcs when interpolate is called, so this is only valid until the next step is taken.

Arguments

Type	Intent	Attributes		Name
class(rk_class),	intent(inout)		::	me
real(kind=wp),	intent(in)		::	t	initial time of the step
real(kind=wp),	intent(in),	dimension(:)	::	x	initial state of the step
real(kind=wp),	intent(in)		::	h	size of the step
real(kind=wp),	intent(in),	dimension(:)	::	xf	final state of the step

procedure, private :: dense_check

private function dense_check(me)

Check that the dense output can be used: the method has one, and it was enabled. If not, an error is raised.

Arguments

Type	Intent	Optional	Attributes		Name
class(rk_class),	intent(inout)			::	me

Return Value logical

procedure, private :: dense_invalidate

private subroutine dense_invalidate(me)

Mark the dense output data as invalid. This must be called before me%funcs is overwritten by a new step.

Arguments

Type	Intent	Optional	Attributes		Name
class(rk_class),	intent(inout)			::	me

procedure(begin_func), private, deferred :: begin_integration

subroutine begin_func(me) Prototype

routine called before integration begins to set up internal variables.

Arguments

Type	Intent	Optional	Attributes		Name
class(rk_class),	intent(inout)			::	me

procedure(properties_func), public, deferred :: properties

pure function properties_func(me) result(p) Prototype

Returns the properties of the method.

Arguments

Type	Intent	Optional	Attributes		Name
class(rk_class),	intent(in)			::	me

Return Value type(rklib_properties)

properties of the method

Source Code

    type,abstract,public :: rk_class

        !! main integration class

        private

        integer :: istatus = 0 !! status code
        logical :: stopped = .false. !! if user has stopped the integration in `f` or `report`.
        integer :: num_steps = 0 !! number of accepted steps taken
        integer :: max_number_of_steps  = huge(1) !! maximum number of steps to take
        integer :: report_rate = 1 !! how often to call report function:
                                   !! `0` : no reporting (same as not associating `report`),
                                   !! `1` : report every point,
                                   !! `2` : report every other point, etc.
                                   !! The first and last point are always reported.

        logical :: stop_on_errors = .false. !! if true, then errors will stop the program
        integer :: n = 0  !! user specified number of variables
        procedure(deriv_func),pointer  :: f      => null()  !! user-specified derivative function
        procedure(report_func),pointer :: report => null()  !! user-specified report function
        procedure(event_func),pointer  :: g      => null()  !! event function (stop when this is zero)
        type(root_method) :: solver = root_method_brent !! the root solver method to use for even finding

        real(wp),dimension(:,:),allocatable :: funcs !! matrix to store the function
                                                     !! evaluations in the step function.
                                                     !! this will be size (`n` x `number_of_registers`).
                                                     !! If the dense output is enabled, and the method
                                                     !! needs extra function evaluations for it
                                                     !! (see [[dense_extra_stages]]), these are stored
                                                     !! in additional columns after the ones for the step,
                                                     !! so the size is (`n` x the number of rows of `dense_b`).

        ! dense output data for the last accepted step:
        logical :: dense_enabled = .false. !! if the dense output was enabled by the user
                                           !! (see [[initialize_variable_step]])
        integer :: dense_form = 0 !! the form of the `dense_b` coefficients
                                  !! (`dense_form_polynomial` or `dense_form_dopri`)
        real(wp),dimension(:,:),allocatable :: dense_b !! dense output coefficients
                                                       !! (allocated if the method has a dense output,
                                                       !! even if it is not enabled)
                                                       !! (`number_of_stages` x `degree`).
                                                       !! See [[dense_coefficients]].
        logical :: dense_available = .false. !! if the dense output data for the last step is valid
        logical :: dense_computed  = .false. !! if `dense_r` has been computed for the last step
        logical :: dense_computing = .false. !! if `dense_r` is being computed (to detect
                                             !! recursive calls to [[interpolate]] from `f`)
        real(wp) :: dense_t = zero !! initial time of the last accepted step
        real(wp) :: dense_h = zero !! size of the last accepted step
        real(wp),dimension(:),allocatable :: dense_x !! initial state of the last accepted step (`n`)
        real(wp),dimension(:),allocatable :: dense_xf !! final state of the last accepted step (`n`)
        real(wp),dimension(:,:),allocatable :: dense_r !! interpolating polynomial coefficients
                                                       !! for the last accepted step (`n` x `degree`)

        contains

        private

        procedure,public :: destroy !! destructor
        procedure,public :: stop => rk_class_stop !! user-callable method to stop the integration
        procedure,public :: status => rk_class_status !! get status code and message
        procedure,public :: failed
        procedure,public :: interpolate !! dense output for the last accepted step
        procedure,public :: dense_interval !! interval of the last accepted step for the dense output

        procedure :: init => initialize_rk_class
        procedure :: begin => begin_integration_rk_class
        procedure :: raise_exception
        procedure :: clear_exception
        procedure :: export_point
        procedure :: dense_coefficients !! dense output coefficients for the method
        procedure :: dense_extra_stages !! additional function evaluations for the dense output
        procedure :: dense_save
        procedure :: dense_check
        procedure :: dense_invalidate
        procedure(begin_func),deferred :: begin_integration
        procedure(properties_func),deferred,public :: properties

    end type rk_class

rk_class Derived Type

Contents

Variables

Type-Bound Procedures

Source Code

type, public, abstract :: rk_class

Inherits

Inherited by

Components

Type-Bound Procedures

procedure, public :: destroy

private subroutine destroy(me)

Arguments

procedure, public :: stop => rk_class_stop

private subroutine rk_class_stop(me)

Arguments

procedure, public :: status => rk_class_status

private subroutine rk_class_status(me, istatus, message)

Arguments

procedure, public :: failed

private function failed(me)

Arguments

Return Value logical

procedure, public :: interpolate

private recursive subroutine interpolate(me, t, x, istatus)

Arguments

procedure, public :: dense_interval

private subroutine dense_interval(me, available, t0, tf, x0, xf)

Arguments

procedure, private :: init => initialize_rk_class

private subroutine initialize_rk_class(me, n, f, report, g, stop_on_errors, max_number_of_steps, report_rate, solver, dense_output)

Arguments

procedure, private :: begin => begin_integration_rk_class

private subroutine begin_integration_rk_class(me)

Arguments

procedure, private :: raise_exception

private subroutine raise_exception(me, error_code)

Arguments

procedure, private :: clear_exception

private subroutine clear_exception(me)

Arguments

procedure, private :: export_point

private subroutine export_point(me, t, x, first_or_last)

Arguments

procedure, private :: dense_coefficients

private pure subroutine dense_coefficients(me, b, form)

Arguments

procedure, private :: dense_extra_stages

private subroutine dense_extra_stages(me)

Arguments

procedure, private :: dense_save

private subroutine dense_save(me, t, x, h, xf)

Arguments

procedure, private :: dense_check

private function dense_check(me)

Arguments

Return Value logical

procedure, private :: dense_invalidate

private subroutine dense_invalidate(me)

Arguments

procedure(begin_func), private, deferred :: begin_integration

subroutine begin_func(me) Prototype

Arguments

procedure(properties_func), public, deferred :: properties

pure function properties_func(me) result(p) Prototype

Arguments

Return Value type(rklib_properties)

Source Code