• Introduction
• Repository structure
• Run the program
  • Download
  • Prerequisites
  • Compilation
  • Running
• Algorithm explanation
  • Phisical background
  • Algorithm description
• How to use

This program computes the coefficients of a function development in a spherical harmonics convergent series, by using a standard mathematical algorithm.

When running the program, you have simply to input the generic shape of the equation and the values of m and l and the coefficients will be calculated.

Some program features:

• Can calculate coefficients for any generic function, entered by the user during the program running.
• coefficients are expressed as complex numbers.
• It works well for each negative or positive value of m, with very good accuracy until m < 5. For higher m values, the accuracy gradually decrease.

NOTE: equations are displayed in green color in order to be correctly visualized in both normal and dark mode.

Here the diagram structure of the repository:

SAFD-agorithm/
├── include/
│   ├── aliases.hpp
│   ├── utils.hpp
│   ├── functions.hpp
├── src/
│   ├── utils.cpp
│   ├── functions.cpp
│   ├── main.cpp
├── scripts/
│   ├── debug.sh
├── test/
│   ├── test_utils.cpp
│   ├── test_functions.cpp
│── README.md
│── LICENSE
│── CITATION.cff
│── CREDITS.md
│── .gitignore
│── .valgrindrc
│── makefile

To download the library you can proceed in two independent ways.

First of all, you need to download the code: go to the main page of the repository and click on the upper right green button called Code. Then click on Download ZIP and wait the download to be completed.

Alternatively you can download the latest version of the repository from the Releases button on the right of the repository main page by clicking on the source code link

To correclty compile and run the program you need some prerequisite installed in your device:

• A g++ compiler.
• The exprtk library, to correctly parse the function.
• My osmanip library, for the output-stream color of the program.
• Optional: the doctest library, to run tests.
• Optional: Valgrind and Cppcheck programs to run the debugging script.

Once you have downloaded the repository, enter the directory through the terminal and type:

make bin/main

to compile the source code.

NOTE: the compilation will be a bit slow, due to the use of the parsing instructions of the exprtk library.

Optionally you can compile also the test code with this command:

make bin/test

If you want to compile both them in one step:

make

This compilation steps should be performed only once.

To run the code you can simply enter this command in the shell:

./bin/main.exe

Extra information about how to move inside the command line once you have ran the code can be found in the How to run section.

If you want to run the tests you have to type:

./bin/test.exe

There is also an extra script to debug the code using Valgrind and Cppcheck, which can be used with some instructions.

You can run Valgrind debugging tools with a specific executable:

./scripts/debug.sh [valgrind-tool-name] [executable-name]

NOTE: where [tool-name] is the Valgrind tool name and [executable-name] is the executable name (you have to indicate also the path to it).

Or you can run them for all the executables of the repository:

./scripts/debug.sh [valgrind-tool-name] all

You can also run Cppcheck tool for a specific source code directory:

./scripts/debug.sh cppcheck [source-code-dir]

Or for a .cpp file only:

./scripts/debug.sh cppcheck [file.cpp]

NOTE: pay attention when running this script with memcheck tool, since it may produce fake errors related to the included libraries. In this case you should prepare a suppression file before running it.

Spherical harmonics are simultaneously eigenfunctions of both the module of the angular momentum and of its arbitrary component along an axis.

They are a family of infinite functions, called , which depend only on the two angles (defined in the spherical transformation of coordinates) and in which l and m are are integers which satisfy this relation: and .

They can construct an orthonormal basis for any other function depending on the same variables; this means that each function can be developed into a spherical harmonics convergent series:

where the coefficients can be written as:

and the spherical harmonics are defined as follows:

where i is the imaginary unit and are the Legendre associated functions, defined in the interval [-1,1] (for the x variable):

with .

The polynomials are called Legendre polynomials and are given by the following recursive relation:

they are also defined in [-1,1] and have .

The algorithm starts from the computation of the Legendre polynomials, for which has been created a function Leg_pol which reproduces the equation (5) (see here). So, nothing special for this one.

To compute the Legendre associated functions of equation (4) it has been firstly defined an n_derivative function to compute the n-th derivative of a real given function, using this recursive relation:

(see here).

The derivative step-size h has been defined with this function:

const double STEP_SIZE = 2 * cbrt( __DBL_EPSILON__ );

d_const h( i_const n, d_const x_0 )
 {
  if ( n < 4 && n > 0 ) return STEP_SIZE * x_0;
  else return n * 0.09;
 }

This derivation algorithm is not optimal, in fact the calculation is not too much accurate for n > 5, but should work not so bad for higher values of n. This is the motivation for which the computation of the equation (2) is precise until m = 5.

Finally, the Legendre associated functions has been computed writing a new function Leg_func, using the equation (4) and the previously defined derivative (see here).

Then, to compute the spherical harmonics defined in (3) it has been simply implemented a complex function sph_arm (see here).

Next step has been the one of writing an integral function to compute the double-integral of equation (2). For this, it has been used the Simpson 1/3 rule:

which has been extended to two-dimensions.

The integration step size for x and y variables has been defined as:

double const h_x = 0.07;
double const h_y = 0.15;

A table of the values of the function for all possible combinations of all x and y points has been created and the Simpson rule has been applied on each row to find integral with reference to y at each x and store the values in an array. Finally, the rule has been again applied on the values of the array to calculate the integral with reference to x (see here).

Another function f_m_l has been then created to compute the final resulting coefficients of equation (2), bu using the integral algorithm defined previously (see here).

At the end, a main program has been provided, in order to run all the necessary code and to parse the function from input, by simply entering its shape during the running of the whole program (see here). This final feature was possible thanks to the exprtk library tools.

When running the program, some options are displayed:

Available options:
   1. Display the single value of a f(m,l) coefficient.
   2. Display all the values of f(m,l) coefficients from m to 0 and from l to 0.
   3. Quit the program. 

Option choice: 

The first one is used to compute a single value of the coefficient for a certain m and l.

The second one is used, instead, to compute all the values of from m to 0 and from l to 0.

Third option explanation is trivial.

When one of the options has been chosen, an output like this will be displayed:

Option choice: 1

Enter the f(th,phi) equation shape (avoid backspaces): 

You can enter the function shape and the values of m and l. For example:

Enter the f(th,phi) equation shape (avoid backspaces): 3*cos(th)+pow(sin(phi),5)
Enter the value of m: 2
Enter the value of l: 3

and the final result is displayed with both real and imaginary parts:

f(2,3) = 0.0546019 + -0.00160564i