Revert "First clean-up and improved documentation"

This reverts commit 63f1a05.

Author: elwaagaa

.github/workflows/pypi-publish.yml

@@ -0,0 +1,38 @@
+name: Publish Python Package
+
+on:
+  release:
+    types: [created]
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write  # This is required for trusted publishing
+
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.10'
+    
+    - name: Install build tools
+      run: |
+        python -m pip install --upgrade pip
+        pip install build twine
+    
+    - name: Build package
+      run: |
+        python -m build
+    
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        user: __token__
+        password: ${{ secrets.PYPI_API_TOKEN }}
+        skip_existing: true
+        verbose: true

.github/workflows/tests.yml

@@ -0,0 +1,59 @@
+name: Tests
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+  schedule:
+    - cron: '0 0 * * 0'  # Weekly on Sundays
+
+defaults:
+  run:
+    shell: bash -l {0}
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ['3.8', '3.9', '3.10', '3.11']
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+    
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e .[dev]
+    
+    - name: Run tests
+      run: |
+        python -m pytest tests/ -v --cov=fma_ions --cov-report=xml
+    
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v4
+      with:
+        token: ${{ secrets.CODECOV_TOKEN }}
+        file: ./coverage.xml
+        fail_ci_if_error: false
+    
+    - name: Run type checking
+      run: |
+        mypy fma_ions/
+    
+    - name: Lint with flake8
+      run: |
+        flake8 fma_ions/
+    
+    - name: Check formatting with black
+      run: |
+        black --check fma_ions/

.readthedocs.yml

@@ -0,0 +1,26 @@
+# .readthedocs.yml
+# Minimal Read the Docs configuration
+version: 2
+
+# Build documentation with Sphinx
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: false
+
+# Python configuration
+python:
+  version: "3.11"
+  install:
+    - method: pip
+      path: .
+      extra_requirements: ["docs"]
+    - requirements: requirements-docs.txt
+
+# Build configuration
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+# Optional: Uncomment to build PDF as well
+# formats: [pdf]

README.md

@@ -1,129 +1,119 @@
-# FMA Ions
+# Frequency Map Analysis for ions
 
-[![PyPI version](https://badge.fury.io/py/fma-ions.svg)](https://badge.fury.io/py/fma-ions)
-[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+Non-linear effects can enhance chaotic motion and limit the performance of accelerators. Frequency Map Analysis (FMA) is a method that probes tune diffusion from particle tracking simulations and identify resonances that are excited. FMA can be used to detect chaotic behaviour in particle acceelerators, by looking at the tune diffusion $d$ 
 
-**A Python package for Frequency Map Analysis of ion beams in particle accelerators**
+$$d =  \log \sqrt{ (Q_{x, 2} - Q_{x, 1})^2 + (Q_{y, 2} - Q_{y, 1})^2}$$
 
-Frequency Map Analysis (FMA) is a powerful technique for studying nonlinear dynamics and detecting chaotic motion in particle accelerators. This package provides comprehensive tools for FMA studies of ion beams at CERN, with support for space charge effects, intra-beam scattering, and tune ripple.
+where $Q_{x, y, 1}$ is the particle tunes in the first number of turns (e.g. first 600 turns) and $Q_{x, y, 2}$ is the tunes of the subsequent turn block (e.g. the next 600 turns).  
 
-## Key Features
+This repository contains FMA classes for ion beams in the CERN accelerator complex, but can also be used for other protons and other set-ups.  
 
-- **🔬 Frequency Map Analysis**: Tune diffusion calculation and resonance identification
-- **⚡ High Performance**: GPU acceleration support for large-scale tracking
-- **🏗️ CERN Integration**: Built-in support for SPS, PS, and LEIR accelerators  
-- **☁️ Cluster Computing**: HTCondor job submission for batch processing
-- **📊 Visualization**: Specialized plotting tools for accelerator physics
-- **🧮 Advanced Physics**: Space charge, IBS, and tune ripple modeling
+![FMA_plot_SPS](https://github.com/ewaagaard/fma_ions/assets/68541324/ed6676c6-9812-486e-81c6-6f6ea0b411de)
 
-## Installation
+### Quick set-up
 
-```bash
-pip install fma_ions
-```
+When using Python for scientific computing, it is important to be aware of dependencies and compatibility of different packages. This guide gives a good explanation: [Python dependency manager guide](https://aaltoscicomp.github.io/python-for-scicomp/dependencies/#dependency-management). An isolated environment allows installing packages without affecting the rest of your operating system or any other projects. A useful resource to handle virtual environments is [Anaconda](https://www.anaconda.com/) (or its lighter version Miniconda), when once installed has many useful commands of which many can be found in the [Conda cheat sheet](https://docs.conda.io/projects/conda/en/4.6.0/_downloads/52a95608c49671267e40c689e0bc00ca/conda-cheatsheet.pdf). A guide to manage conda environments is found [here](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html). 
+
+To directly start using `fma_ions`, create an isolated virtual environment with conda and perform a local install to use the `fma_ions`. Run in the terminal to clone the repository, install a virtual environment (with all requirements) and then a local editable install of `fma_ions`:
 
-For GPU support:
-```bash
-pip install cupy-cuda11x  # CUDA 11.x
-pip install cupy-cuda12x  # CUDA 12.x
 ```
+git clone https://github.com/ewaagaard/fma_ions.git
+conda create --name fma_env python=3.11.7
+conda activate fma_env
+python -m pip install -r venvs/requirements.txt
+cd ..
+python -m pip install -e fma_ions
+```
+
+#### Cloning repos for PS and SPS sequences
 
-For CERN accelerator models:
-```bash
+The `fma_ions` relies on sequence generators for PS and SPS ions, which requires MADX sequence files from [git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) from [acc-models](https://gitlab.cern.ch/acc-models). Clone these repositories as submodules inside the `fma_ions`:
+```
 cd fma_ions/data/
 git clone https://gitlab.cern.ch/acc-models/acc-models-sps.git
 git clone https://gitlab.cern.ch/acc-models/acc-models-ps.git
 ```
+If this command is executed correctly, two repositories `acc-models-ps` and `acc-models-sps` should appear inside the `data` folder with content. 
 
-## Quick Start
-
-```python
-from fma_ions import FMA, SPS_Flat_Bottom_Tracker
+#### GPU support
 
-# Basic FMA analysis
-fma = FMA()
-d, Qx, Qy = fma.run_SPS()  # Run default SPS analysis
-fma.plot_tune_diagram(Qx, Qy, d)
+Tracking many particles for millions of turns can take a long time. Although the default context for most functions is with CPU, most of them also contain support for GPUs for faster particle tracking. If you machine supports GPU usage, check out [Xsuite GPU/Multithreading support](https://xsuite.readthedocs.io/en/latest/installation.html#gpu-multithreading-support). The `cupy` should already be installed from `venvs/requirements.txt`, but it can be useful to run the following lines again:
 
-# Comprehensive SPS tracking with space charge
-tracker = SPS_Flat_Bottom_Tracker()
-tracker.track_SPS(n_turns=1000)
-tracker.plot_tracking_data()
+```
+conda install mamba -n base -c conda-forge
+pip install cupy-cuda11x
+mamba install cudatoolkit=11.8.0
 ```
 
-## Physics Background
-
-FMA detects chaotic motion by analyzing tune diffusion:
-
-$$d = \log_{10} \sqrt{(Q_{x,2} - Q_{x,1})^2 + (Q_{y,2} - Q_{y,1})^2}$$
-
-Where $Q_{x,y,1}$ and $Q_{x,y,2}$ are tunes calculated from different turn blocks.
-
-**Interpretation:**
-- $d < -5$: Regular motion (stable)
-- $d > -3$: Chaotic motion (unstable)
-
-## Package Structure
-
-- **`FMA`**: Core analysis class with tune diffusion calculations
-- **`SPS_Flat_Bottom_Tracker`**: Comprehensive SPS particle tracking
-- **`Submitter`**: HTCondor job submission for CERN cluster
-- **`Tune_Ripple_SPS`**: Power converter ripple simulation
-- **Sequence makers**: PS, SPS, and LEIR lattice generation
-- **Beam parameters**: Ion-specific configurations for different species
-
-## Documentation
-
-Comprehensive documentation is available at: https://fma-ions.readthedocs.io/
-
-- [Installation Guide](https://fma-ions.readthedocs.io/en/latest/installation.html)
-- [Quick Start Tutorial](https://fma-ions.readthedocs.io/en/latest/quickstart.html)
-- [Physics Background](https://fma-ions.readthedocs.io/en/latest/physics.html)
-- [API Reference](https://fma-ions.readthedocs.io/en/latest/autoapi/index.html)
+## FMA class
 
-## Examples
+The `FMA` class contains all the methods and imports all helper functions needed to track particle objects and analyze the tune diffusion. The class is instantiated by
+```
+import fma_ions
+fma = fma_ions.FMA() 
+```
+Optional arguments can be added, such as specific output destinations for turn-by-turn (TBT) data and plots, number of turns to track, shape of particle object, longitudinal position offset `z0` and so on. Arbitrary [Xsuite](https://xsuite.readthedocs.io/en/latest/) lines can be used, although helper classes provide standard PS and SPS lattice models. 
 
-See the [`examples/`](examples/) directory and [documentation examples](https://fma-ions.readthedocs.io/en/latest/examples.html) for:
+The FMA happens in several steps: 
+1) first a line with space charge (SC) is returned, and the particle object to be tracked. Input is an Xsuite line (without space charge) and `beamParams`, which is a data class containing bunch intensity `Nb`, bunch length `sigma_z`, normalized emittances `exn` and `eyn`, and the integer tune of the accelerator `Q_int`, since this technique can only detect fractional tunes. An example structure for this `beamParams` class is found in `fma_ions.BeamParameters_SPS()`. 
+2) TBT `x` and `y` data are returned, tracking for the specified attribute `num_turns` (default 1200) in the FMA class.
+3) The diffusion coefficient `d` and individual particle tunes `Qx` and `Qy` are returned from the NAFF algorithm used in the FMA method
+4) `Qx`, `Qy` and `d` can be plotted in the initial particle distribution and in the final tune diagram of the particles. 
+```
+line_with_SC, particles = fma.install_SC_and_generate_particles(line, beamParams)
+x, y = fma.track_particles(particles, line_with_SC)
+d, Qx, Qy = fma.run_FMA(x, y)
 
-- Dynamic aperture studies
-- Space charge effect analysis  
-- Tune ripple impact assessment
-- Multi-species ion comparisons
-- HTCondor batch processing
+# Set point, e.g for SPS
+Qh_set, Qv_set = 26.30, 26.25 
 
-## Contributing
+# Tune footprint range
+plot_range  = [[26.0, 26.35], [26.0, 26.35]]
 
-We welcome contributions! Please see our [Contributing Guide](https://fma-ions.readthedocs.io/en/latest/contributing.html) for details on:
+# Generate plots.
+fma.plot_FMA(d, Qx, Qy, Qh_set, Qv_set,'SPS', plot_range)
+fma.plot_initial_distribution(x, y, d, case_name='SPS')
+```
+Initial distributions provide useful insights where the tune diffusion happens inside the distribution. 
 
-- Development setup
-- Code style guidelines  
-- Testing procedures
-- Documentation standards
+![SPS_Initial_distribution](https://github.com/ewaagaard/fma_ions/assets/68541324/35a343bf-fc7d-4215-a4a2-08fe2e43be19)
 
-## Citation
+### Built-in sequences 
 
-If you use this software in your research, please cite:
+SPS and PS standard Pb lattice models from Xsuite are contained in helper data classes. These can be instantiated easily by using:
+```
+import fma_ions
+fma_sps = fma_ions.FMA()
+fma_sps.run_SPS()
 
-```bibtex
-@software{waagaard2024fma_ions,
-  author = {Elias Waagaard},
-  title = {fma_ions: Frequency Map Analysis for ion beams at CERN},
-  year = {2024},
-  publisher = {GitHub},
-  url = {https://github.com/ewaagaard/fma_ions}
-}
+fma_ps = fma_ions.FMA()
+fma_ps.run_PS()
 ```
+which call standard PS and SPS lattices, and perform the FMA described in the previous section with default parameters. If the tracking has already been done, plots can easily be generated from saved TBT data by using
+```
+fma_sps = fma_ions.FMA()
+fma_sps.run_SPS(load_tbt_data=True)
+```
+### Custom beams and tunes
 
-## License
+Custom beam intensities, tunes, charge states and masses can be provided. The `FMA` class rematches provided tunes and generates the desired beam
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+```
+import fma_ions
 
-## Acknowledgments
+# Initialize FMA object and intialize beam (mass is in atomic units)
+fma_sps = fma_ions.FMA()
+fma_sps.run_custom_beam_SPS(ion_type='O', m_ion=15.99, Q_SPS=8., Q_PS=4., qx=26.30, qy=26.19, Nb=82e8)
+```
+### Longitudinal position or momentum offset
 
-- CERN for accelerator models and computing resources
-- Xsuite team for tracking infrastructure
-- NAFF library for frequency analysis algorithms
+To investigate tune diagram sidebands and effects of synchrotron oscillations on off-momentum particles, non-zero `z0` or `delta0` can be provided to generate the particle object. If a uniform beam is used, `n_linear` determines the resolution of the meshgrid in normalized coordinates $X$ and $Y$, so `n_linear=100` generates 10 000 particles unformly distributed up to a desired beam size (e.g. 10 $\sigma$). 
+```
+import fma_ions
 
+fma_sps = fma_ions.FMA(z0=0.15, n_linear=200)
+fma_sps.run_SPS()
+```
 
+![FMA_plot_SPS](https://github.com/ewaagaard/fma_ions/assets/68541324/d1d69eec-fc0d-4ccd-a34c-a1820cc6f604)