# Penning trap simulation

![](./images/100_particles.gif)

[Repo](https://github.uio.no/FYS3150-G2-2023/Project-3)

[Documentation](https://pages.github.uio.no/FYS3150-G2-2023/Project-3/)

## Requirements

### Operating systems

- Linux
    - Has been tested on [Fedora 38](https://fedoraproject.org/)
    - Will most likely work on other Linux distributions
- MacOS
    - Might work, but hasn't been tested
- Windows
    - Will most likely not work

### Tools

- Profiling
    - [gprof](https://ftp.gnu.org/old-gnu/Manuals/gprof-2.9.1/html_mono/gprof.html)
    - [scalasca](https://www.scalasca.org/)
    - [score-p](https://www.vi-hps.org/projects/score-p)

### Libraries

- Python
    - [matplotlib](https://matplotlib.org/)
    - [numpy](https://numpy.org/)

- C++
    - [openmp](https://www.openmp.org/)
    - [armadillo](https://arma.sourceforge.net/)


## Compiling

Compiling is as easy as running this command while being inside the src directory:

```shell
    make
```

## Running programs

### C++ binaries

To run **main** or **test_suite**, just run this command while being inside src:

```shell
    ./<program-name>
```

### Python scripts

#### Install libraries

Before running the scripts, make sure that all libraries are installed.
Using pip, you can install all requirements like this:

```shell
    pip install -r requirements.txt
```

This recursively install all the packages that are listed in **requirements.txt**.

#### Running scripts

For the Python scripts, run them from the src directory like this:

```shell
    python scripts/<script-name>
```

If you have any problems running the scripts, you might have to run this instead:

```shell
    python3 scripts/<script-name>
```

### Batch system

For the **frequency_narrow_sweeps_long** program, the is a script called 
**job.script** that comes along with it. This is to be able to run it on a
batch system using Slurm if you have access to one. 
This is the recommended way to use this program as it takes approximately 90 
minutes to complete when using 16 cores.

If you happen to have such a system available to you, then you should clone
this repo on that system, then compile it by running:

```shell
    make frequency_narrow_sweeps_long
```

You might have to load the Armadillo library before compiling.

After compiling, you can schedule it by running:

```shell
    sbatch job.script
```

## Performance

This section aims to give an idea to the time it takes for the program to
run so that you know a bit what to expect if you decide to run it for
yourself.

### CPU

The times mentioned here are times achieved on a computer with these 
specifications:

- CPU model
    - Intel i7-9850H
- Threads
    - 12
- Clock speed
    - 4.6GHz

### Times

All times mentioned use the **evolve_RK4** method.

Running a simulation with 100 particles without particle interactions over
40000 steps takes around 1.8 seconds. With particle interactions, it takes
around 4.8 seconds.

**potential_resonance_wide_sweep** takes around 56 seconds to complete.

**potential_resonance_narrow_sweep** takes around 172 seconds to complete.

**potential_resonance_narrow_sweep_interaction** takes around 936 seconds to 
complete.

## Credits

The Doxygen theme used here is 
[doxygen-awesome-css](https://github.com/jothepro/doxygen-awesome-css).