Installation
============

GASFIR requires Python 3.8 or higher.

Dependencies
------------

**Core** (installed automatically with ``pip install gasfir``):

* **NumPy** ≥ 1.26.4
* **SciPy** ≥ 1.15.3
* **Numba** ≥ 0.61.2 — JIT compilation for kernel performance
* **pandas** ≥ 1.5.0

**Retrieval extras** (``pip install gasfir[retrieval]``):

* **lmfit** ≥ 1.3.3 — parameter fitting and residual construction
* **emcee** ≥ 3.1.0 — MCMC sampling
* **CMA-ES** (``cma``) ≥ 3.0.0 — global optimisation
* **tqdm** ≥ 4.60.0 — progress bars
* **corner** ≥ 2.2.0 — posterior corner plots

**Development extras** (``pip install gasfir[dev]``):

* pytest, pytest-cov, black, isort, flake8, mypy, tabulate

**Documentation extras** (``pip install gasfir[docs]``):

* Sphinx, sphinx-rtd-theme, sphinx-autodoc-typehints

Installation Methods
--------------------

Using pip
~~~~~~~~~

Core only (ionization calculations, unit conversions, parameter store)::

   pip install gasfir

With fitting and retrieval pipeline::

   pip install gasfir[retrieval]

With all extras::

   pip install gasfir[retrieval,dev,docs]

Using conda (recommended for development)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

::

   conda env create -f environment.yml
   conda activate gasfir
   pip install -e ".[retrieval,dev,docs]"

To recreate ``environment.yml`` after changing dependencies::

   conda env export -n gasfir --no-builds | grep -v "^prefix:" > environment.yml

From source
~~~~~~~~~~~

::

   git clone https://gitlab.mpcdf.mpg.de/gaf/gasfir.git
   cd gasfir
   pip install -e ".[retrieval,dev,docs]"

Verification
------------

After installation, verify the core package::

   import gasfir
   print(gasfir.__version__)

   from gasfir import create_pulse, get_parameters, get_diabatic_ionization_probability
   laser  = create_pulse(800, 1e14, 0, 6)
   params = get_parameters("Hydrogen_SFA")
   prob   = get_diabatic_ionization_probability(pulse=laser, param_dict=params)
   print(f"P = {prob:.4e}")

Verify the retrieval extras::

   from gasfir.retrieval import RetrievalConfig
   from gasfir.fitting   import ret_residual_function
   print("Retrieval extras OK")

Troubleshooting
---------------

**ImportError: No module named 'lmfit'**
   Fitting and retrieval require the retrieval extras::

      pip install gasfir[retrieval]

**ImportError: No module named 'numba'**
   ::

      pip install --upgrade numba

**Slow first run**
   Numba compiles kernels on the first call.  Subsequent calls are fast.
   Pre-warm with a short trial pulse before your main calculation.

For development setup, see :doc:`development/contributing`.