Joel Berger > PerlGSL-DiffEq-0.08 > PerlGSL::DiffEq

Download:
PerlGSL-DiffEq-0.08.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.08   Source  

NAME ^

PerlGSL::DiffEq - A Perlish Interface to Solving ODEs using GSL v1.15+

SYNOPSIS ^

 use PerlGSL::DiffEq;
 
 #Differential Equation(s)
 sub eqn {
 
   #initial conditions returned if called without parameters
   unless (@_) {
     return (0,1);
   }
 
   my ($t, @y) = @_;
   
   #example:   y''(t)==-y(t)
   my @derivs = (
     $y[1],     # y'[0] = y[1]
     -$y[0],    # y'[1] = - y[0]
   );
   return @derivs;
 }
 
 $sine = ode_solver(\&eqn, [0, 2*3.14, 100]);

DESCRIPTION ^

This module provides a Perl-ish interface to the Gnu Scientific Library's (GSL) ODEIV2 library, (documentation). This library is the new ordinary differential equation solver as of GSL version 1.15.

NAMESPACE

This module used to be named Math::GSLx::ODEIV2, a name I never liked. After writing interfaces to GSL's integration libraries I decided to unite the modules under a common namespace PerlGSL. This namespace/distribution contains modular interfaces to the GSL. Read more in the documentation for PerlGSL.

INTERFACE STABILITY

This module is in an beta state. It needs more tests and the ability to configure more of the options that the GSL library allows. Currently this module leans on the fact that GSL has an extensive test suite. While the author has put some thought into the interface it may change in the future as the above mentioned functionality is added or as bugs appear. Bug reports are encouraged!

Also, as of version 0.06, support for including a Jacobian of the system has been added, including the step types that this allows, however this functionality is almost totally untested. Until some of the stiff/extreme test cases can be ported from GSL the author is not certain the the functionality has been properly implemented. Sadly t/sine.* pass even when not properly implemented, which is unnerving. Caveat emptor.

EXPORTED FUNCTIONS ^

ode_solver

This is the main function of the module.

 $solution = ode_solver( $diffeq_code_ref, $t_range)

or

 $solution = ode_solver( $diffeq_code_ref, $t_range, $opts_hashref)

or

 $solution = ode_solver( [$diffeq_code_ref, $jacobian_code_ref], $t_range, $opts_hashref)

Before detailing how to call ode_solver, lets see how to construct the differential equation system.

the differential equation system

The differential equation system is defined in a code reference (in the example $diffeq_code_ref). This code reference (or anonymous subroutine) must have a specific construction:

Optionally the system may be further described with a code reference which defines the Jacobian of the system (in the example $jacobian_code_ref). Again, this code reference has a specific construction. The arguments will be passed in exactly the same way as for the equations code reference (though it will not be called without arguments). The returns should be two array references.

The Jacobian code reference is only needed for certain step types, those step types whose names end in _j.

required arguments

ode_solver requires two arguments, they are as follows:

first argument

The first argument may be either a code reference or an array reference containing one or two code references. In the single code reference form this represents the differential equation system, constructed as described above. In the array reference form, the first argument must be the differential equation system code reference, but now optionally a code reference for the Jacobian of the system may be supplied as the second item.

second argument

The second argument, $t_range, specifies the time values that are used for the calculation. This may be used one of two ways:

optional argument (the options hash reference)

The third argument, $opts_hashref, is a hash reference containing other options. They are as follows:

return

The return is an array reference of array references. Each inner array reference will contain the time and function value of each function in order as above. This format allows easy loading into PDL if so desired:

 $pdl = pdl($solution);

of course one may recover one column by simple use of a map:

 @solution_t_vals  = map { $_->[0] } @$solution;
 @solution_y1_vals = map { $_->[1] } @$solution;
 ...

For a usage example see the "SYNOPSIS" for a sine function given by y''(t)=-y(t).

EXPORTABLE FUNCTIONS ^

get_step_types

Returns the available step types which may be specified in the "ode_solver" function's options hashref. Note that those step types whose name end in _j require the Jacobian.

get_gsl_version

A simple function taking no arguments and returning the version number of the GSL library as specified in gsl/gsl_version.h. This was originally used for dependency checking but now remains simply for the interested user.

FUTURE GOALS ^

On systems with PDL installed, I would like to include some mechanism which will store the numerical data in a piddle directly, saving the overhead of creating an SV for each of the pieces of data generated. I envision this happening as transparently as possible when PDL is available. This will probably take some experimentation to get it right.

SEE ALSO ^

PerlGSL
Math::ODE
Math::GSL::ODEIV
GSL
PDL, website

SOURCE REPOSITORY ^

http://github.com/jberger/PerlGSL-DiffEq

AUTHOR ^

Joel Berger, <joel.a.berger@gmail.com>

COPYRIGHT AND LICENSE ^

Copyright (C) 2012 by Joel Berger

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The GSL is licensed under the terms of the GNU General Public License (GPL)

syntax highlighting: