am
==

.. py:module:: am


Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/am/grid/index
   /autoapi/am/model/index


Exceptions
----------

.. autoapisummary::

   am.AmError


Classes
-------

.. autoapisummary::

   am.ComputeError
   am.ConfigError
   am.ModelGrid
   am.Model


Package Contents
----------------

.. py:exception:: AmError



   Base exception for am errors.


.. py:class:: ComputeError



   Error during model computation.


.. py:class:: ConfigError



   Error parsing an .amc configuration file.


.. py:class:: ModelGrid(path: pathlib.Path, params: xarray.Dataset, args_fn: Callable[Ellipsis, list[str]], max_workers: int | None = None)

   Run an am model over a grid of parameter values.

   Parameters
   ----------
   path:
       Path to the ``.amc`` template file.
   params:
       xarray Dataset defining the parameter space.  Two forms are supported:

       * **Regular (Cartesian) grid** — coordinates on independent dimensions::

           xr.Dataset(coords={"elevation": [30, 45, 60], "pwv": [0.5, 1.0, 2.0]})

       * **Irregular grid** — variables sharing one dimension::

           xr.Dataset({"elevation": ("profile", elev), "pwv": ("profile", pwv)})

   args_fn:
       Callable that maps parameter values to an am args list.  Keyword
       argument names must match coordinate/variable names in *params*::

           args_fn=lambda elevation, pwv: [
               "0", "GHz", "350", "GHz", "0.5", "GHz",
               str(elevation), "deg", str(pwv),
           ]

   max_workers:
       Number of worker processes (default: ``os.cpu_count()``).


   .. py:method:: compute() -> xarray.Dataset

      Run all models and return an xarray Dataset.

      The output Dataset has the same dimensions and coordinates as *params*,
      plus a ``frequency`` dimension.  Each requested am output (e.g.
      ``tb_rj``, ``transmittance``) becomes a data variable.



.. py:class:: Model(path, args)

   An am atmospheric model loaded from an ``.amc`` configuration file.

   Thin wrapper around the Rust ``_Model`` that returns xarray Datasets
   for :attr:`outputs` and :meth:`jacobian`.

   Parameters
   ----------
   path:
       Path to the ``.amc`` file.
   args:
       Positional substitution values for ``%1``, ``%2``, … placeholders
       in the config (frequency grid, zenith angle, PWV scale, etc.).


   .. py:method:: compute()

      Run the radiative transfer computation.



   .. py:property:: frequency
      :type: numpy.ndarray


      Frequency grid in GHz.



   .. py:property:: outputs
      :type: xarray.Dataset


      Computed output spectra as an xarray Dataset.

      Dimension is ``frequency`` (GHz).  Only outputs listed in the
      ``output`` directive of the ``.amc`` file are present.
      Empty before :meth:`compute` is called.



   .. py:property:: variables
      :type: list[str]


      Names of fit/differentiation variables defined in the config.



   .. py:property:: n_variables
      :type: int


      Number of fit/differentiation variables.



   .. py:method:: jacobian() -> xarray.Dataset

      Compute Jacobians of all outputs w.r.t. fit variables.

      Returns an xarray Dataset with dimensions ``(variable, frequency)``.
      The ``.amc`` config must define fit variables (parameters with scales).

      Raises
      ------
      ConfigError
          If no fit variables are defined in the ``.amc`` config.



   .. py:method:: summary() -> str

      Full resolved model configuration summary.