The ‘finesse.cymath’ extension¶
Using fast mathematical routines¶
The sub-module finesse.cymath
is a Cython extension containing external
declarations from the C headers "math.h"
and "complex.h"
as well as C
implemented functions defining common mathematical routines required for the various
parts of Finesse. Where applicable, these methods are declared as cpdef
such that
they can be used from other Cython extensions (as a fast C function call) and Python
modules (as a slower Python function call). Note that it is only the function call
overhead that is different for any cpdef
function - the code inside is implemented
in pure C for all finesse.cymath
functions and this is the same for both the
generated C function and Python function.
The complex data type
One of the key elements exposed by finesse.cymath
to other Cython extensions is
the C type definition complex_t
- defined as np.complex128_t
which is just
equivalent to the double complex C type.
Whenever your Cython extension requires complex numbers, always use this type definition rather than defining your own or redefining from elsewhere. To do this, simply add the following to your .pyx file(s):
from finesse.cymath cimport complex_t
Importing standard "math.h"
functions
Here is the general process for using a standard C math function on non-complex types:
By inspecting the
cdef extern from "math.h"
block at the start offinesse/cymath/math.pxd
, check that the C function you need already exists within this.If it is already present, then you can simply cimport the function. For example, if you need the
sin
function acting on double type values then simply cimport as:from finesse.cymath.math cimport sinOtherwise, refer to the necessary function signature in the Common Mathematical Functions C reference and add this to the
cdef extern
block. For example, if you need the base-2 logarithm routine then simply add it as follows:# In this block (already present) cdef extern from "math.h" nogil: # all the existing functions... double log2(double x)
Importing standard "complex.h"
functions
Similarly to above:
By inspecting the
cdef extern from "complex.h"
block at the start offinesse/cymath/complex.pxd
, check that the C function you need already exists within this.If it is already present, then you can simply cimport the function. For example, if you need the
csqrt
function then simply cimport as:from finesse.cymath.complex cimport csqrtOtherwise, refer to the necessary function signature in the Complex Number Arithmetic C reference and add this to the
cdef extern
block. For example, if you need the projection routine then simply add it as follows:# In this block (already present) cdef extern from "complex.h" nogil: # all the existing functions... double complex cproj(double complex z)
Importing custom fast arithmetic functions from finesse.cymath
In addition to the standard C functions, this module also provides various fast mathematical
routines which are not defined in the C numerics libraries. These are typically declared in
the relevant *.pxd
file and then defined in the corresponding .pyx
file; however some
may be defined immediately in the *.pxd
if they are declared as inline
.
An example of such a function is the crotate
routine which sits in finesse.cymath.complex
and performs the rotation of a complex number (of type complex_t
) by a given phase in radians.
Importing such functions, at a C level, is as simple as the standard routines. For this example,
one can just do:
from finesse.cymath.complex cimport crotate
to get access to this function.
If you need to implement any custom fast (C level) mathematics to use in some other finesse cython
extension, then declare and define such functions in an identical way to those that exist within
the sub-modules of finesse.cymath
.