sda.rlc.fit_rlc
===============

.. py:module:: sda.rlc.fit_rlc

.. autoapi-nested-parse::

   A module for fitting an RLC circuit to a pulsed signal.

   The RLC circuit is a linear, second-order differential equation, and it can be
   used to model the response of a circuit to a pulsed signal. The circuit can be
   critically damped, underdamped, or overdamped, and the response can be
   oscillatory or not;
   For the underline physics, see the Word document in BP25 folder.

   The module provides a function to calculate the current across the RLC circuit
   in response to a pulsed signal, and another function to calculate the current
   across the RL circuit in response to a pulsed signal. The module also provides
   a function to calculate the pulsed signal itself.

   The module also provides a main block to plot the current across the RLC circuit
   in response to a pulsed signal, and the current across the RL circuit in response
   to a pulsed signal.



Attributes
----------

.. autoapisummary::

   sda.rlc.fit_rlc.times


Functions
---------

.. autoapisummary::

   sda.rlc.fit_rlc.pulsed_signal
   sda.rlc.fit_rlc.rlc_current
   sda.rlc.fit_rlc.rl_current
   sda.rlc.fit_rlc.initial_guess
   sda.rlc.fit_rlc.fit_signal_with_current


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

.. py:function:: pulsed_signal(t, tau, V)

   Return a pulsed signal, serving as an input signal to the RLC circuit.

   The pulse is defined here as step function that goes from 0 to V at t = 0,
   and stays at V for 0 < t <= tau. The pulse is 0 for t > tau.

   :param t: Time in seconds.
   :type t: :py:class:`float`
   :param tau: Pulse duration in seconds.
   :type tau: :py:class:`float`
   :param V: Pulse amplitude in volts.
   :type V: :py:class:`float`

   :returns: The pulse value at time t.
   :rtype: :py:class:`float`


.. py:function:: rlc_current(t, R, L, C, tau, V)

   Compute current across the RLC circuit, in response to a pulsed signal.

   Schema of the RLC circuit:

   ::

       ----------C----------L------┐
       ↑                           │
       │                           │
      e(t)                         R
       │                           │
       │                           │
       ----------------------------┘

   :param t: Time in seconds.
   :type t: :py:class:`float`
   :param R: Resistance in Ohms.
   :type R: :py:class:`float`
   :param L: Inductance in Henry.
   :type L: :py:class:`float`
   :param C: Capacitance in Farad.
   :type C: :py:class:`float`
   :param tau: Pulse duration in seconds.
   :type tau: :py:class:`float`
   :param V: Pulse amplitude in volts.
   :type V: :py:class:`float`

   :returns: The current across the RLC circuit at time t.
   :rtype: :py:class:`float`

   :raises ValueError: If the circuit is critically damped.


.. py:function:: rl_current(t, R, L, tau, V)

   Compute current across the RL circuit, in response to a pulsed signal.

   Schema of the RL circuit:

   ::

       ----------L-----┐
       ↑               │
       │               │
       e(t)            R
       │               │
       │               │
       ----------------┘

   :param t: Time in seconds.
   :type t: :py:class:`float`
   :param R: Resistance in Ohms.
   :type R: :py:class:`float`
   :param L: Inductance in Henry.
   :type L: :py:class:`float`
   :param tau: Pulse duration in seconds.
   :type tau: :py:class:`float`
   :param V: Pulse amplitude in volts.
   :type V: :py:class:`float`

   :returns: The current across the RL circuit at time t.
   :rtype: :py:class:`float`


.. py:function:: initial_guess(times, current, V, tau = None)

   Determine the initial guess for the RLC circuit.

   The initial guesses are based on the following assumptions:
   - The inductance is the inverse of the slope of the current at t = 0.
   - The resistance is related to the times T the current reaches 0.05 of its maximum value.
   - The capacitance is linked to oscillations in current.

   :param times: Time in seconds.
   :type times: :py:class:`np.ndarray`
   :param current: Current in Amperes.
   :type current: :py:class:`np.ndarray`
   :param V: Pulse amplitude in Volts.
   :type V: :py:class:`float`
   :param tau: Pulse duration in seconds. If None, the pulse duration is estimated as the time
               at which the current reaches its maximum value. Defaults to None.
   :type tau: :py:class:`float`, *optional*

   :returns: The initial guesses for the resistance, inductance, capacitance, and pulse duration
             of the RLC circuit.
   :rtype: :py:class:`tuple[float`, :py:class:`float`, :py:class:`float`, :py:class:`float]`


.. py:function:: fit_signal_with_current(times, current, V, tau = None)

   Fit the current across the RLC circuit to a pulsed signal.

   :param times: Time in seconds.
   :type times: :py:class:`np.ndarray`
   :param current: Current in Amperes.
   :type current: :py:class:`np.ndarray`
   :param V: Pulse amplitude in Volts.
   :type V: :py:class:`float`
   :param tau: Pulse duration in seconds. If None, the pulse duration is estimated as the time
               at which the current reaches its maximum value. Defaults to None.
   :type tau: :py:class:`float`, *optional*

   :returns: The resistance, inductance, and capacitance of the RLC circuit.
   :rtype: :py:class:`tuple[float`, :py:class:`float`, :py:class:`float]`


.. py:data:: times