.. SPDX-FileCopyrightText: 1992-2026 NWO-I/SRON Space Research Organisation Netherlands
..
.. SPDX-License-Identifier: CC-BY-4.0

Fortran API Interface
=====================

.. warning::
   This source code documentation was generated by AI and may contain errors or inaccuracies.
   Users should verify information against the actual source code and consult the official
   SPEX user manual for authoritative usage instructions.

Introduction
------------

The SPEX Fortran interface provides comprehensive access to all X-ray spectral analysis capabilities through a modern, object-oriented Fortran API. This interface serves as the foundation for both the interactive SPEX command prompt and the Python interface, offering direct programmatic control over all SPEX functionality.

Architecture Overview
---------------------

The SPEX Fortran interface is built using a **layered architecture** that separates concerns and provides multiple access levels:

**Application Layer**
  - ``spex.f90``: Main interactive program
  - Utility programs: ``stepcontour``, ``trafo``, ``linid``, etc.

**Interface Layer**
  - ``spexapi.f90``: Unified Fortran API (facade pattern)
  - ``spex_command.f90``: Interactive command interface

**Core Library Layer**
  - ``spexio``: Data input/output and spectrum management
  - ``spexmodel``: Spectral modeling and atomic physics
  - ``spexfit``: Parameter estimation and statistical analysis
  - ``spexplot``: Plotting and visualization

**Utility Layer**
  - ``spexutils``: Common utilities and helper functions
  - ``spexmath``: Mathematical operations and algorithms

Target Audiences
----------------

**End Users**
  Use the interactive command prompt (``spex``) for X-ray spectral analysis. The command interface provides intuitive access to all SPEX capabilities through text commands.

**Python Developers**
  Access SPEX functionality through the Python interface, which wraps the Fortran API to provide Pythonic access to spectral analysis tools.

**Fortran Developers**
  Use the ``spexapi.f90`` module directly for custom applications, batch processing, or integration with other Fortran codes.

**SPEX Contributors**
  Extend SPEX by adding new models, fitting algorithms, or analysis tools using the modular library architecture.

Getting Started
---------------

**For Interactive Use**::

    $ spex
    SPEX4> data mydata.res mydata.spo
    SPEX4> comp pow
    SPEX4> fit
    SPEX4> plot

**For Fortran Development**::

    program my_analysis
        use spex_api
        implicit none

        type(sapi) :: spex
        integer    :: ier

        ! Initialize SPEX
        call spex%init()

        ! Load data
        call spex%data('mydata.res', 'mydata.spo', ier)

        ! Add model component
        call spex%comp('pow', 1, 1, ier)

        ! Perform fit
        call spex%fit(ier)

        ! Clean up
        call spex%final()
    end program

**For Python Development**::

    import pyspex

    # Initialize session
    s = pyspex.Spex()

    # Load data and fit model
    s.data('mydata.res', 'mydata.spo')
    s.comp('pow')
    s.fit()

    # Access results
    chi2 = s.fit_statistic()

Development Guidelines
---------------------

**Adding New Functionality**
  1. Implement core functionality in appropriate library (spexio, spexmodel, etc.)
  2. Add API method to ``spexapi.f90`` for programmatic access
  3. Add command handler to ``spex_command.f90`` for interactive use
  4. Update Python bindings if needed

**Error Handling**
  All Fortran API methods use consistent error reporting through integer status codes:

  - ``ier = 0``: Success
  - ``ier > 0``: Warning or non-fatal error
  - ``ier < 0``: Fatal error requiring intervention

**Memory Management**
  SPEX uses automatic memory management through Fortran derived types with proper initialization and finalization procedures.

**Performance Considerations**
  - Core computational routines are optimized for large datasets
  - Memory allocation is minimized during fitting iterations
  - Parallel processing support where applicable

Module Documentation
-------------------

The following sections provide detailed documentation for each component of the SPEX Fortran interface:

.. toctree::
   :maxdepth: 2

   fortran/spex/spex
   fortran/spexfit/spexfit
   fortran/spexmodel
   fortran/spexio/spexio
   fortran/spexplot/spexplot
   fortran/spexutils/index