simopt.curve
============

.. py:module:: simopt.curve

.. autoapi-nested-parse::

   Curve class for plotting and analysis.





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

.. py:class:: CurveType(*args, **kwds)

   Bases: :py:obj:`enum.Enum`


   Enumeration for different curve styles.


   .. py:attribute:: REGULAR
      :value: 'regular'



   .. py:attribute:: CONF_BOUND
      :value: 'conf_bound'



   .. py:property:: style
      :type: tuple[str, int]


      Returns linestyle and linewidth for the curve type.


.. py:class:: Curve(x_vals: collections.abc.Sequence[int | float], y_vals: collections.abc.Sequence[int | float])

   Base class for all curves.

   Initialize a curve with x- and y-values.

   :param x_vals: Values of horizontal components.
   :type x_vals: Sequence[int | float]
   :param y_vals: Values of vertical components.
   :type y_vals: Sequence[int | float]

   :raises TypeError: If x_vals or y_vals are not numeric.
   :raises ValueError: If x_vals and y_vals have different lengths or if they contain
       non-numeric values.


   .. py:property:: x_vals
      :type: tuple[float, Ellipsis]


      Values of horizontal components.


   .. py:property:: y_vals
      :type: tuple[float, Ellipsis]


      Values of vertical components.


   .. py:property:: n_points
      :type: int


      Number of points in the curve.


   .. py:method:: lookup(x_val: float) -> float

      Lookup the y-value of the curve at an intermediate x-value.

      :param x_val: X-value to lookup.
      :type x_val: float

      :returns: Y-value corresponding to x, or NaN if x_val is out of range.
      :rtype: float

      :raises TypeError: If x_val is not numeric.



   .. py:method:: compute_crossing_time(threshold: float) -> float

      Compute the first time at which a curve drops below a given threshold.

      :param threshold: Value for which to find the first crossing time.
      :type threshold: float

      :returns: First time at which the curve drops below the threshold.
      :rtype: float



   .. py:method:: compute_area_under_curve() -> float

      Compute the area under a curve.

      :returns: Area under the curve.
      :rtype: float



   .. py:method:: curve_to_mesh(mesh: collections.abc.Iterable[float]) -> Curve

      Create a curve defined at equally spaced x values.

      :param mesh: Collection of uniformly spaced x-values.
      :type mesh: Iterable[float]

      :returns: A curve with equally spaced x-values.
      :rtype: Curve

      :raises TypeError: If mesh is not an iterable of numeric values.



   .. py:method:: curve_to_full_curve() -> Curve

      Create a curve with duplicate x- and y-values to indicate steps.

      :returns: A curve with duplicate x- and y-values.
      :rtype: Curve



   .. py:method:: plot(color_str: str = 'C0', curve_type: CurveType = CurveType.REGULAR) -> matplotlib.lines.Line2D

      Plot a curve.

      :param color_str: String indicating line color, e.g., "C0", "C1", etc.
      :type color_str: str
      :param curve_type: Type of line.
      :type curve_type: CurveType

      :returns: Curve handle, useful when creating legends.
      :rtype: Line2D

      :raises ValueError: If an invalid curve type is provided.