simopt.curve_utils
==================

.. py:module:: simopt.curve_utils

.. autoapi-nested-parse::

   Curve utility functions.

   This module provides utility functions for manipulating and analyzing curves.





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

.. py:function:: mean_of_curves(curves: collections.abc.Iterable[simopt.curve.Curve]) -> simopt.curve.Curve

   Compute the pointwise mean of a collection of curves.

   All curves must have identical starting and ending x-values.

   :param curves: A collection of curves to aggregate.
   :type curves: Iterable[Curve]

   :returns: A curve representing the pointwise mean across all input curves.
   :rtype: Curve

   :raises TypeError: If the input is not an iterable of Curve objects.


.. py:function:: quantile_of_curves(curves: collections.abc.Iterable[simopt.curve.Curve], beta: float) -> simopt.curve.Curve

   Compute the pointwise quantile of a collection of curves.

   All curves must have identical starting and ending x-values.

   :param curves: A collection of curves to aggregate.
   :type curves: Iterable[Curve]
   :param beta: The quantile level to compute (e.g., 0.5 for median).
   :type beta: float

   :returns: A curve representing the pointwise quantile across the input curves.
   :rtype: Curve

   :raises TypeError: If input is not a valid collection of Curve objects.


.. py:function:: cdf_of_curves_crossing_times(curves: collections.abc.Iterable[simopt.curve.Curve], threshold: float) -> simopt.curve.Curve

   Compute the CDF of crossing times from a collection of curves.

   The crossing time is defined as the first x-value where a curve crosses a given
   threshold.

   :param curves: A list of curves to analyze.
   :type curves: list[Curve]
   :param threshold: The y-value at which to detect the first crossing.
   :type threshold: float

   :returns: A curve representing the cumulative distribution of crossing times.
   :rtype: Curve

   :raises TypeError: If input is not a list of Curve objects.


.. py:function:: quantile_cross_jump(curves: collections.abc.Iterable[simopt.curve.Curve], threshold: float, beta: float) -> simopt.curve.Curve

   Compute a curve with a jump at the quantile of the crossing times.

   The curve is piecewise-constant with a single jump located at the specified quantile
   of the first crossing times across the input curves.

   :param curves: A list of curves to analyze.
   :type curves: list[Curve]
   :param threshold: The y-value at which to detect the first crossing.
   :type threshold: float
   :param beta: The quantile level (e.g., 0.5 for median crossing time).
   :type beta: float

   :returns: A piecewise-constant curve with a jump at the quantile crossing time,
             if finite.
   :rtype: Curve

   :raises TypeError: If input types are incorrect.


.. py:function:: difference_of_curves(curve_1: simopt.curve.Curve, curve_2: simopt.curve.Curve) -> simopt.curve.Curve

   Compute the difference between two curves (curve_1 - curve_2).

   The x-values of both curves must align exactly.

   :param curve_1: The first curve (minuend).
   :type curve_1: Curve
   :param curve_2: The second curve (subtrahend).
   :type curve_2: Curve

   :returns: A curve representing the pointwise difference.
   :rtype: Curve

   :raises TypeError: If inputs are not Curve instances or are incompatible.


.. py:function:: max_difference_of_curves(curve_1: simopt.curve.Curve, curve_2: simopt.curve.Curve) -> float

   Compute the maximum pointwise difference between two curves (curve_1 - curve_2).

   :param curve_1: The first curve (minuend).
   :type curve_1: Curve
   :param curve_2: The second curve (subtrahend).
   :type curve_2: Curve

   :returns: The maximum difference between the two curves at any x-value.
   :rtype: float

   :raises TypeError: If the inputs are not Curve instances or are incompatible.