firecrown.utils
===============

.. py:module:: firecrown.utils

.. autoapi-nested-parse::

   Some utility functions for patterns common in Firecrown.



Attributes
----------

.. autoapisummary::

   firecrown.utils.ST


Classes
-------

.. autoapisummary::

   firecrown.utils.YAMLSerializable
   firecrown.utils.ClLimberMethod
   firecrown.utils.ClIntegrationMethod
   firecrown.utils.ClIntegrationOptions


Functions
---------

.. autoapisummary::

   firecrown.utils.base_model_from_yaml
   firecrown.utils.base_model_to_yaml
   firecrown.utils.upper_triangle_indices
   firecrown.utils.save_to_sacc
   firecrown.utils.compare_optional_arrays
   firecrown.utils.compare_optionals
   firecrown.utils.cached_angular_cl
   firecrown.utils.make_log_interpolator


Module Contents
---------------

.. py:data:: ST

.. py:class:: YAMLSerializable

   Protocol for classes that can be serialized to and from YAML.


   .. py:method:: to_yaml()

      Return the YAML representation of the object.



   .. py:method:: from_yaml(yaml_str)
      :classmethod:


      Load the object from YAML.



.. py:function:: base_model_from_yaml(cls, yaml_str)

   Create a base model from a yaml string.


.. py:function:: base_model_to_yaml(model)

   Convert a base model to a yaml string.


.. py:function:: upper_triangle_indices(n)

   Returns the upper triangular indices for an (n x n) matrix.

   generator that yields a sequence of tuples that carry the indices for an
   (n x n) upper-triangular matrix. This is a replacement for the nested loops:

   for i in range(n):
     for j in range(i, n):
       ...

   :param n: the size of the matrix
   :return: the generator


.. py:function:: save_to_sacc(sacc_data, data_vector, indices, strict = True)

   Save a data vector into a (new) SACC object, copied from `sacc_data`.

   Note that the original object `sacc_data` is not modified. Its contents are
   copied into a new object, and the new information is put into that copy,
   which is returned by this method.

   If `strict` is True (the default), then we must overwrite the entire data
   vector. If `strict` is False, then we only overwrite the data at the
   specified indices.

   :param sacc_data: SACC object to be copied. It is not modified.
   :param data_vector: Data vector to be saved to the new copy of `sacc_data`.
   :param indices: SACC indices where the data vector should be written.
   :param strict: Whether to check if the data vector covers all the data
       already present in the sacc_data.
   :return: A copy of `sacc_data`, with data at `indices` replaced with `data_vector`.


.. py:function:: compare_optional_arrays(x, y)

   Compare two arrays, allowing for either or both to be None.

   :param x: first array
   :param y: second array
   :return: whether the arrays are equal


.. py:function:: compare_optionals(x, y)

   Compare two objects, allowing for either or both to be None.

   :param x: first object
   :param y: second object
   :return: whether the objects are equal


.. py:class:: ClLimberMethod

   Bases: :py:obj:`YAMLSerializable`, :py:obj:`str`, :py:obj:`enum.Enum`

   .. autoapi-inheritance-diagram:: firecrown.utils.ClLimberMethod
      :parts: 1


   This class defines Cl limber methods.


   .. py:attribute:: GSL_QAG_QUAD


   .. py:attribute:: GSL_SPLINE


.. py:class:: ClIntegrationMethod

   Bases: :py:obj:`YAMLSerializable`, :py:obj:`str`, :py:obj:`enum.Enum`

   .. autoapi-inheritance-diagram:: firecrown.utils.ClIntegrationMethod
      :parts: 1


   This class defines Cl integration methods.


   .. py:attribute:: LIMBER


   .. py:attribute:: FKEM_AUTO


   .. py:attribute:: FKEM_L_LIMBER


.. py:class:: ClIntegrationOptions(/, **data)

   Bases: :py:obj:`pydantic.BaseModel`

   .. autoapi-inheritance-diagram:: firecrown.utils.ClIntegrationOptions
      :parts: 1


   Options for angular power spectrum integration.


   .. py:attribute:: model_config

      Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict].



   .. py:attribute:: method
      :type:  Annotated[ClIntegrationMethod, BeforeValidator(_validate_cl_integration_method)]


   .. py:attribute:: limber_method
      :type:  Annotated[ClLimberMethod, BeforeValidator(_validate_cl_limber_method)]


   .. py:attribute:: l_limber
      :type:  int | None
      :value: None



   .. py:attribute:: limber_max_error
      :type:  float | None
      :value: None



   .. py:attribute:: fkem_chi_min
      :type:  float | None
      :value: None



   .. py:attribute:: fkem_Nchi
      :type:  int | None
      :value: None



   .. py:method:: serialize_method(value)
      :classmethod:


      Serialize the method parameter.



   .. py:method:: serialize_limber_method(value)
      :classmethod:


      Serialize the limber_method parameter.



   .. py:method:: model_post_init(_, /)

      Initialize the WeakLensingFactory object.



   .. py:method:: get_angular_cl_args()

      Get the arguments to pass to pyccl.angular_cl.



.. py:function:: cached_angular_cl(cosmo, tracers, ells, p_of_k_a=None | Callable[[npt.NDArray[np.int64]], npt.NDArray[np.float64]], p_of_k_a_lin=None | pyccl.Pk2D | str, int_options = None)

   Wrapper for pyccl.angular_cl, with automatic caching.

   :param cosmo: the current cosmology
   :param tracers: tracers indicating the measurements to be correlated
   :param ells: ell values at which to calculate the power spectrum
   :param p_of_k_a: function that computes the power spectrum
   :param l_limber: the maximum ell for the non-limber integration
   :param p_of_k_a_lin: function that returns the linear power spectrum


.. py:function:: make_log_interpolator(x, y)

   Return a function object that does 1D spline interpolation.

   If all the y values are greater than 0, the function
   interpolates log(y) as a function of log(x).
   Otherwise, the function interpolates y as a function of log(x).
   The resulting interpolater will not extrapolate; if called with
   an out-of-range argument it will raise a ValueError.