Package: pyRKIntegrator
Runge-Kutta and Runge-Kutta-Nystrom integratorsThis project contains a series of adaptive generic Runge-Kutta and Runge-Kutta-Nystrom integrators developed in C++, with a Python interface.The code has been optimized under AVX/AVX2 vectorization directives using the Intel(r) C++ compiler (icpc). Although this is thedefaultcompilation mode, it is not strictly required as the makefile will automatically default to GNU if the Intel compilers are not found.The default optimization mode isfastalthough it can be changed using the variableOPTL, e.g.,makeOPTL=2DeploymentAMakefileis provided within the tool to automate the installation for easiness of use for the user. To install the tool simply create a virtual environment as stated below or use the system Python. Once this is done simply type:makeThis will install all the requirements and install the package to your active python. To uninstall simply usemakeuninstallThe previous operations can be done one step at a time usingmakerequirementsto install all the requirements;makepythonto compile and;makeinstallto install the tool.Virtual environmentThe package can be installed in a Python virtual environement to avoid messing with the system Python installation.
Next, we will useCondafor this purpose.
Assuming that Conda is already installed, we can create a virtual environment with a specific python version and name (my_env) usingcondacreate-nmy_envpython=3.8The environment is placed in~/.conda/envs/my_env.
Next we activate it be able to install packages usingcondaitself or another Python package manager in the environment directory:condaactivatemy_envThen just follow the instructions as stated above.Runge-Kutta methodsThe Runge-Kutta methods are a family of numerical integrators for ODEs. They require a function so thatdydx = f(x,y)The C++ API requires defining a the function to integrate asvoidodefun(doublex,doubley[],intn,doubledydx[])whereyanddydxhavencomponents already allocated. The Runge-Kutta integrator is called as followsRK_PARAMrkp=rkdefaults(xspan);// Standard Runge-Kutta parametersRK_OUTrko=odeRK(testfun,xspan,y0,n,rkp);// Runge-Kutta integratorwhererkpcontains the ODE integration parameters (seeRK.h) andrkois the output structure containing:A return value,rko.retval, that is > 0 in case of success or < 0 in case of failue. A value of 0 indicates that theodeRKroutine has not been run.The number of integration stepsrko.n.An error valuerko.err.The solution,rko.xandrko.y.
The available Runge-Kutta schemes are:Euler-Heun 1(2) (eulerheun12)Bogacki-Shampine 2(3) (bogackishampine23)Fehlberg 4(5) (fehlberg45)Cash-Karp 4(5) (cashkarp45)Dormand-Prince 4-5 (dormandprince45)Calvo 5(6) (calvo56)Dormand-Prince 7(8) (dormandprince78)Curtis 8(10) (curtis810)Hiroshi 9(12) (hiroshi912)Runge-Kutta-Nystrom methodsThe Runge-Kutta-Nystrom methods are a family of numerical integrators for smooth second order ODEs. They require a function so thatdy2dx2 = f(x,y)The C++ API requires defining a the function to integrate asvoidodefun(doublex,doubley[],intn,doubledy2dx2[])whererkpcontains the ODE integration parameters (seeRK.h) andrkois the output structure containing:A return value,rko.retval, that is > 0 in case of success or < 0 in case of failue. A value of 0 indicates that theodeRKroutine has not been run.The number of integration stepsrko.n.An error valuerko.err.The solution,rko.x,rko.yandrko.dy.
The available Runge-Kutta-Nystrom schemes are:Runge-Kutta-Nystrom 3(4) (rkn34)Runge-Kutta-Nystrom 4(6) (rkn46)Runge-Kutta-Nystrom 6(8) (rkn68)Runge-Kutta-Nystrom 10(12) (rkn1012)C and C++ implementationsThere is a C and a C++ implementation of the algorithms. The language can be chosen in theMakefileby setting theUSE_CPPvariable. The compilation of the examples and the python tools will follow.makeUSE_CPP=ON/OFFThe Python interfaceThe Python interface allows using the Runge-Kutta and Runge-Kutta-Nystrom integrators using Python's cython. The wrapper can be compiled usingmakepythonNote that this will create a.sothat must be in the same directory ofRungeKutta.py. Otherwise, the Python interface is accessed without the speedup of compiled code.In Python, the Runge-Kutta module should be first usingimportpyRKIntegratorasrkThe function to integrate must be defined asdefodefun(x,y,n,dydx):# For Runge-Kuttadefodefun(x,y,n,dy2dx):# For Runge-Kutta-Nystromwhereyanddydxordy2dxare vectors that have already been allocated (of sizen). Access to the parameters structure is provided by theodesetclass:params=rk.odeset()# For Runge-Kutta and Runge-Kutta-NystromThis will initiate using default parameters, which can be changed by using key arguments or by modifying the class fields. The access to the integratos is:x,y,err=rk.odeRK(odefun,xspan,y0,odeset)# For Runge-Kuttax,y,dy,err=rk.odeRKN(odefun,xspan,y0,dy0,odeset)# For Runge-Kutta-NystromExamples 1 to 4 include examples of advanced features to use with the integrator.Event and output functionsEvent detection and output functions are a characteristic of this set of integrators. They can be set using theRK_PARAMstructure in C++RK_PARAMrkp;rkp.eventfcn=eventfun;rkp.outputfcn=outputfun;or theodesetclass in Pythonodeset=rk.odeset(eventfun=eventfun,outputfun=outputfun)Output functionsOutput functions allow retrieving the integrated values right after a successful integration step. A value of either1or0must be returned to continue or stop the integration. The implementation in C++ isintoutputfun(doublex,doubley[],intn){/* Some code */return1;// or 0 to stop integration}and in Pythondefoutputfun(x,y,n):# Some codereturn1# or 0 to stop integrationEvent functionsEvent functions allow for solving a problem so thatg(x) - val = 0using a root solving algorithm. This is useful, for example, to detect when the integrator reaches a certain value (seeexample2.pyfor a more comprehensive usage). The implementation in C++ isinteventfun(doublex,doubley[],intn,doublevalue[1],intdirection[1]){/* Some code */return1;// or 0 to stop integration}and in Pythondefeventfun(x,y,n,value,direction):# Some codereturn1# or 0 to stop integrationWherevalueis a mathematical expression describing the event. An event occurs when value(i) is equal to zero.direction0 if all zeros are to be located.+1 locates only zeros where the event function is increasing.-1 locates only zeros where the event function is decreasing.
Regardingdirection, only 0 is implemented.