Advanced Usage
==============

Batch Processing over Multiple Intensities
------------------------------------------

Use :func:`~gasfir.get_diabatic_ionization_probability_vec` to compute
probabilities for a list of pulses in one parallelised call.  It performs the
heavy pulse pre-computation once and evaluates the kernel for every pulse
across all CPU cores:

.. code-block:: python

    import numpy as np
    from gasfir import (
        create_pulse,
        get_parameters,
        get_diabatic_ionization_probability_vec,
    )

    intensities = np.logspace(13, 15, 20)
    pulses = [create_pulse(800, I, 0, 30) for I in intensities]
    params = get_parameters("Hydrogen_SFA")

    probs = get_diabatic_ionization_probability_vec(pulses, params)
    # probs is a list of length len(pulses)

Elliptical Polarization
-----------------------

Use the :func:`~gasfir.create_pulse` companion :func:`gasfir.create_pulse_ellip`.
The minor-axis intensity is the major-axis intensity divided by ``ellip_frac``
(``ellip_frac=1`` gives circular polarization):

.. code-block:: python

    from gasfir.pulse import create_pulse_ellip

    # wavelength (nm), intensity (W/cm²), CEP (rad), duration (optical cycles)
    laser = create_pulse_ellip(800, 1e14, 0.0, 10, ellip_frac=2)

For full control, construct :class:`~gasfir.EllipticalCosNPulse` directly.  The
field amplitudes are set by the two peak intensities (major and minor axis):

.. code-block:: python

    from gasfir import EllipticalCosNPulse, OptCyc_au

    laser = EllipticalCosNPulse(
        central_wavelength=800,                 # nm
        peak_intensity=1e14,                     # W/cm² (major axis)
        FWHM=OptCyc_au(10, 800),                 # FWHM in a.u. (10 optical cycles)
        cep=0.0,
        peak_intensity2=5e13,                    # W/cm² (minor axis)
        envelope_N=8,
    )

DataFrame-based Workflow
------------------------

:func:`~gasfir.ret_gasfir_P_for_dataFrame` takes a DataFrame with a
``"pulses"`` column and returns a **fast probability function**.  The heavy
pre-computation runs once; the returned closure accepts a parameter dict and
can be called repeatedly (e.g. inside an optimiser):

.. code-block:: python

    import pandas as pd
    from gasfir import ret_gasfir_P_for_dataFrame, create_pulse, get_parameters

    df = pd.DataFrame({
        "pulses": [create_pulse(800, I, 0, 30) for I in [5e13, 1e14, 2e14]],
        "intensity": [5e13, 1e14, 2e14],
    })

    P_func = ret_gasfir_P_for_dataFrame(df)   # pre-computes once, returns a callable
    params = get_parameters("Hydrogen_SFA")
    df["P"] = P_func(params)                  # evaluate for these parameters