Package: gerk
Generalized Explicit Runge-Kutta (GERK)A package for the curious mathematicians and engineers who want to experiment the Runge-Kutta method with their own coefficients.PyPI linkGitHub linkContentsRunge-Kutta OverviewWhat is Gerk?How to use GerkAttributesCondition ArgumentsMethodsExampleCreating the Gerk Objectplot exampleget_approximations exampleget_errors exampleefficiency_graph exampleAdaptive Runge-Kutta MethodsAdaptive Runge-Kutta ExampleRunge-Kutta OverviewRunge-Kutta methods aim to numerically solve ordinary differential equations of the form:$$
\frac{\text{d}y}{\text{d}x}=f(x,y)
$$with a given initial condition $(x_0, y_0)$.We define a member of the Runge-Kutta family with aButcher tableau:The above tableau is often abbreviated toThe Butcher tableau presents the categories of coefficients that will be used in our Runge-Kutta method.The $n^\text{th}$ evaluation of the solution will be denoted as $(x_n, y_n)$. We also define $h$ as the time step i.e. the step size from the previous approximation to the next, and therefore$$
x_{n+1} = x_{n} + h
$$Before defining $y_n$, we must familiarize ourselves with the array $k$. We define the $i^{\text{th}}$ row of $k$ at $(x_n, y_n)$ as:$$
k_i(x_n, y_n) = f\left(x_n + c_i h, y_n + \sum_{j=1}^{i-1} a_{ij}k_j(x_n, y_n)\right)
$$where $f$ is the function defined in the differential equation above. Note the recursion in the second argument of $f$ where we sum rows preceding $k_{i}$ and apply a scale factor of $a_{ij}$.We now have everything we need to calculate $y_{n+1}$:$$
y_{n+1} = y_{n} + h \sum_{i=1}^{r}b_i k_{i}(x_n, y_n)
$$The idea is to calculate various slopes at point $y_n$ to ascertain a weighted of the ascent (or descent) and add it to the previous approximation.What is Gerk?Most packages for the Runge-Kutta method usually have the coefficients $a_{ij}$, $b_i$ and $c_i$ determined beforehand for known methods such as theForward-Euler method, the1/4 rule,the 3/8 ruleetc, but do not allow one to customerize their own Runge-Kutta.Gerk is an easy interface to allow the user to determine their own coefficient values for the Runge-Kutta method. The package can return the approximations in the form of an array, a plot of the approximated curve (using matplotlib) and also compare with real values (if available) to produce errors and even an efficiency graph!How to use GerkWe can simply importGerkin the following way:from gerk import GerkAttributesAs seen in mathematics above, there is quite a bit information required to execute the Runge-Kutta method. This has been broken down into arguments to be passed into theGerkclass:AThe $A$ matrix in the Butcher tableau. Thismustbe a lower triangular matrix that is formatted as a list of lists that contain floats, decimals or integersNote: Fractions must be in a string e.g. "1/3"bThe $b$ array. Must be a list of floats, decimals or integerscThe $c$ array. Must be a list of floats, decimals or integersinitial_conditionsAtuplethat acts as the coordinate of the initial condition values $(x_0, y_0)$finalThe value of $x$ for which we terminate the Runge-Kutta methodtime_stepsThe number of times steps you want to apply on the from the starting point $x_0$ tofinal. Must be an integerfuncThe function expression to be numerically integratedreal_values(Optional) Acallablewhich is the explicit solution to the initial value problemora list of real valuesNotethe list must be of sizetime_steps + 1Condition ArgumentsThere is no consensus to what conditions must hold regarding the coefficients you choose for your method, however, some known Runge-Kutta methods do consistently conform to some known conditions.These conditions are$$\sum_{i=1}^{r}b_i=1 \ \ \ \ \sum_{i=1}^{r}b_ic_i = 1/2 \ \ \ \ \sum_{j=1}^{r}a_{ij} = c_i$$which can be enforced by the boolean parameterscondition_b,condition_bcandcondition_Acrespectively. These parameters have been set toFalseby default to allow the user to freely explore and experiment.Methodssolvecan be run to calculate the approximate value of $y_n$ for each time stepefficiency_graphplots the efficiency graph of the Runge-Kutta method for the defined system for time steps 100, 1,000, 10,000, 100,000 and 1,000,000Oncesolvehas been run, the following methods will be available to execute:plotCreates a graph of the approximated curve. If you have set the (optional)real_valuesargument, you can plot both the approximated and exact curves in one plot by settingwith_real=True. You also have the option to amendx_labelandy_labelwhich are arugments of the methodget_approximationreturns the approximated values of $y$ in a listget_errorsreturns the error for each approximation $y_n$ in a list (only applicable ifreal_valuesargument was used)ExampleCreating the Gerk ObjectIn the example below, we will use the 3/8-th rule to approximate the following initial value problem:$$
\frac{\text{d}y}{\text{d}x} = y
$$with the initial condition $(0, 1)$ and will be making approximations up to $x=5$ with 1000 time steps.The 3/8-th rule has the following Butcher tableau:The $A$ lower triangular matrix in the Butcher tableau above can be implemented in the following way:A = [ 
        ["1/3"], # Remember, fractions must be passed as strings
        ["-1/3", 1],
        [1, -1, 1]
]Note that if you would rather use "square" matrices, you can also defineAas:A = [
        [0,0,0,0], 
        ["1/3", 0, 0, 0],
        ["-1/3", 1, 0, 0],
        [1, -1, 1, 0]
]Either version ofAis acceptable inGerk.Now for thebandcvectors:b = ["1/8", "3/8", "3/8", "1/8"]

c = [0, "1/3", "2/3", 1]We now have sufficient information to createGerkobject. However, we know the solution to the initial value problem is $y=e^x$. So in this case, we can utilise thereal_valuesparameter by setting it to the lambda function:lambda x,y: math.exp(x)Now we are ready to create theGerkobject:import math

rk_obj = Gerk(
        A=A, 
        b=b, 
        c=c, 
        initial_conditions=(0, 1), 
        time_steps=1000, 
        final=5,
        func=lambda x, y: y, # Remember, you must define both x and y as variables, even if one is not used
        real_values = lambda y: math.exp(y)
    )We can now runrk_obj.solve().After runningsolve, 3 methods are now available to us:plot exampleWe can now plot our approximated curve. Note that because we have definedreal_values, we also have the option to plot the exact solution by setting thewith_realflag toTrue.rk_obj.plot(with_real=True)get_approximations exampleThe approximated values $y_n$ for each timestep can be obtained by runningget_approximationswhich returns a list of the values:rk_obj.get_approximations[2:5][Decimal('1.010062750717580079753282335'), Decimal('1.015132034738508612169525261'), Decimal('1.020226760387164317916560525')]Notethat this is apropertyand not a method, so no need for parentheses.get_errors exampleThe errors for each time step can also be obtained if thereal_valueparameter has been set. In this example, we setreal_values=lambda x: math.exp(x)which will be used to calculate the error at each step.By simply callingget_errors, we obtain all the errors in the form of a list (again, no need for parentheses):rk_obj.get_errors[2:5][Decimal('0.00001258363341213062577786389261'), Decimal('0.00001897012278968249653135224731'), Decimal('0.00002542036040854158088425155254')]Efficiency GraphWe can create an efficiency graph for the Runge-Kutta method provided thatreal_valueshas been set to a callable function. This can be done by simply running:rk_obj.efficiency_graph()Note:You do not need to runsolve()beforehand to produce efficiency graph.Adaptive Runge-Kutta MethodsThere is an alternate way to utilise the Runge-Kutta method by employing an additional distinct $b$ array. The Butcher tableau for such methods take the form:where $b^*_i$ is the additional $b$ array.This method is not too disimilar to the original Runge-Kutta method. We calculate the $k$'s in the same way as before, but there is an extra step when evaluating $y_{n+1}$.Although we do calculate $y_{n+1}$ in same way outlined above, we also calculate $\hat{y}_{n+1}$:$$
y_{n+1} = y_{n} + h \sum_{i=1}^{r}b_i\cdot k_{i}(x_n, y_n) \ \ \ \ \ \ \ \ \ \hat{y_{n+1}} = y_{n} + h \sum_{i=1}^{r} b_{i}^{\ast}\cdot k_{i}(x_n, y_n)
$$Notethat the calculation for $\hat{y}$ requires the use of $y_n$ andnot$\hat{y}_n$.For every time step, we calculate the following error:$$
E := \left|y_{n+1}-\hat{y}_{n+1}\right|
$$Now we define the tolerance, $\mathcal{E}$, which will act as the maximum acceptable value for $E$.If $E<\mathcal{E}$, then we accept the value of $y_{n+1}$ and we increment $x_{n}$ by $h$ and start the process again for $x_{n+1}$ and $y_{n+1}$ as normal.However, if $E\geq\mathcal{E}$, we will need to adjust the value of $h$ and redo the calculation with this renewed time step value in an attempt to satisfy the condition $E<\mathcal{E}$.The value of $h$ will be adjusted as follows:$$
h \rightarrow 0.9\cdot h \cdot\sqrt[n]{\frac{h}{\mathcal{E}}}
$$where $n=\min\left(p,q\right)$, where $p$ and $q$ are the orders $^1$ of $b_i$ and $b^*_i$ respectively.$^1$ A Runge-Kutta method with matrix $A$ and arrays $b$ and $c$ has order $p$ if$$
\sum_{i=1}^{p}b_i = 1 \ \ \ \ \sum_{i=1}^{p}b_ic_i = 1/2 \ \ \ \ \sum_{j=1}^{p}a_{ij} = c_i  \ \ \ \
$$These are similar to the conditions defined above with the parameterscondition_b,condition_bcandcondition_Acrespectively.However, it is difficult to calculate the order when these conditions are not met. Therefore, to simplify things, $h$ will be re-calculated in the same way whether these conditions are met or not. In the future, we aim to come up with a solution to reflect a more appropriate solution.Note that you can impose the same conditions on $b^*_i$ with the parameterscondition_b_starandcondition_b_star_cfor the first two conditions. Again, these are set toFalseby default.Adaptive Runge-Kutta exampleIn this example, we will try to numerically integrate$$
\frac{\text{d}y}{\text{d}x}=-2xy
$$with initial conditions $(-5, 1.3887943865\times 10^{-11})$. Note that the exact solution is $y=e^{-x^2}$.Here we will use the Fehlberg RK1(2) method which has the following Butcher tableau:We require an additional argument for the $b^*$ vector, which inGerkis calledb_star:A = [
        ["1/2"], # Remember, fractions need to be in strings
        ["1/256", "255/256"]
    ]

b = [
    "1/512", "255/256", "1/512"
]

b_star = [
    "1/256", "255/256", 0
]

c = [
    0, "1/2", 1
]The idea of discretizations is meaningless in this context since the step size is constantly changing. Therefore, thetime_stepsparameter will be used as thestartingtime step, which we will set to 0.01 in this example.We will set the tolerance to a punitive value of 0.00000001. _Note: iftoleranceis not set, a default value of 0.001 will be used instead.We can now create ourGerkobject,solveandplot:adj_rk = Gerk(
    A=A, 
    b=b, 
    c=c, 
    initial_conditions=(-5.0, 1.3887943865e-11),
    time_steps=0.001, # Remeber, this needs to be the step size NOT the number of discretizations
    final=5,
    func=lambda x,y: -2*x*y,
    real_values=lambda x: math.exp(-x**2),
    b_star=b_star,
    tolerance=0.00001
)

adj_rk.solve()

adj_rk.plot(with_real=True)In this case, the Runge-Kutta approximation is so accurate that we can barely see the exact curve!Efficiency graphs are not available for the adaptive Runge-Kutta method as the number discretizations is not constant.Additional NotesI have taken some inspiration fromthis paperby M. A. Demba, N.Senu and F. Ismail which helped in understanding the adaptive RK method and fromJim Verner'sextensive research in exploring Runge-Kutta possibilitiesFuture works will includeAcceptnumpy.arrayas parameter inputExtend and generalize the adaptive Runge-Kutta Method, an idea inspired byM. A. Demba, N.Senu and F. IsmailFind solution to finding RK orders when conditions are not met