**Getting Started with FlowCyPy**
---------------------------------

This section is designed to help you set up **FlowCyPy**, familiarize yourself with its components, and explore its capabilities through hands-on experimentation. By following the steps below, you will gain the foundational knowledge and skills needed to contribute meaningfully to the project.

Installation
~~~~~~~~~~~~

To get started, clone the **FlowCyPy** repository and install the necessary dependencies:

.. code-block:: bash

  git clone https://github.com/MartinPdeS/FlowCyPy.git
  cd FlowCyPy
  python -m pip install -e .[testing, documentation]  # For Windows/Linux
  python -m pip install -e ".[testing, documentation]"  # For macOS
  python -m pytest .  # Run tests to validate the installation

.. admonition:: Mini Objective

    After installation, run `pytest` to ensure the software is functioning correctly. If any tests fail, investigate the issues and review the related code to familiarize yourself with its structure and functionality.

Explore the Documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~

The **FlowCyPy** documentation provides an in-depth guide to the library’s features, components, and workflows. It is a valuable resource for learning how to configure and run simulations effectively.

- Access the documentation: `FlowCyPy Documentation <https://martinpdes.github.io/FlowCyPy>`_

In particular, explore the **Examples** section, which contains tutorials and step-by-step guides for simulating various flow cytometry experiments.

.. admonition:: Mini Objective

  Identify an example in the **Examples** section that simulates scatterers with different sizes. Run the example and analyze the output to understand the relationship between scatterer properties and signals.

Run Example Simulations
~~~~~~~~~~~~~~~~~~~~~~~

Pre-written scripts in the `examples` folder demonstrate typical workflows in **FlowCyPy**. Running these scripts is a great way to explore the software’s capabilities.

.. code-block:: bash

  cd examples
  python example_simulation.py

.. admonition:: Mini Objective

  - Modify an example script to compare the signals generated by a detector with high noise versus one with minimal noise. Observe and interpret the differences.
  - Adjust detector parameters to induce saturation by using larger scatterers or increasing the laser's optical power. Analyze how saturation impacts the output signal.

Study Core Components
~~~~~~~~~~~~~~~~~~~~~~

The core components of **FlowCyPy** are modular and designed for flexibility. Familiarizing yourself with these files will deepen your understanding of the library:

- **`scatterer.py`**: Manages particle distributions and their optical properties.
- **`source.py`**: Defines laser source characteristics, such as wavelength and power.
- **`detector.py`**: Configures detectors, including noise levels, responsitivity, and resolution.
- **`flow_cytometer.py`**: Integrates scatterers, sources, and detectors to simulate flow cytometry experiments.

.. admonition:: Mini Objective

  - Use `scatterer.py` to simulate scatterers with distinct refractive indices. Visualize how these variations affect forward and side scatter signals.
  - Modify `source.py` to experiment with different laser wavelengths. Explore the impact on scattering behavior when particle sizes are comparable to or smaller than the wavelength.
  - In `detector.py`, reduce the number of signal digitization bins to simulate a low-resolution detector. Observe the effects on signal clarity and precision.
  - Configure an entire flow cytometry experiment using `flow_cytometer.py` and compare the performance of detectors placed at different angles.

Stretch Goals
~~~~~~~~~~~~~

For advanced exploration, consider the following challenges:

1. Experiment with the `NoiseSetting` module:

   - Combine multiple noise types (e.g., shot noise, thermal noise) to simulate real-world imperfections.
   - Analyze how cumulative noise impacts signal quality.

2. Create a custom particle population:

   - Design a population with a bimodal size distribution.
   - Simulate and analyze the resulting scatter signals.

3. Investigate coincidence analysis:

   - Use the `EventCorrelator` to study coincidences between detectors.
   - Examine how altering particle concentration or detector placement affects the coincidence rate.

Forking the Repository
~~~~~~~~~~~~~~~~~~~~~~~

In most cases, interns working on **FlowCyPy** will not need to fork the repository. Instead, you can clone the main repository directly and work within branches to implement features or fix issues. However, for specific long-term tasks or independent projects, forking may be required.

If forking is necessary:

- Fork the repository on GitHub.
- Clone your forked version locally.
- Sync your fork regularly with the main repository to stay up-to-date.


.. admonition:: Mini Objective

    - Understand the difference between cloning and forking. If you are working collaboratively on shared tasks, stick to cloning unless explicitly instructed otherwise.