transientbvd Package

Deactivation (deactivation.py)

TransientBVD - Deactivation Transient Analysis

This module provides functions for analyzing the transient response of resonant circuits modeled by the Butterworth-Van Dyke (BVD) equivalent circuit in a deactivation scenario.

It includes methods for evaluating decay times, optimizing parallel resistance for damping, and computing transient currents using the system’s characteristic polynomial.

transientbvd.deactivation.deactivation_current(t, i0, transducer, rp=None, di0=0.0, d2i0=None)[source]

Calculate the transient current i(t) for the deactivation case (MOSFET opens).

Notes

For open-circuit termination (Rp -> infinity), the characteristic polynomial can include a root at 0. If i(0)=i0, i’(0)=0, and i’’(0)=0 are enforced, this can collapse into a constant-current solution.

Therefore, if d2i0 is not provided, it is inferred from the dominant oscillatory eigenpair as approximately: d2i0 ~= -(omega_d**2) * i0.

Parameters:

t (float) – Time in seconds.
i0 (float) – Initial current i(0) in ampere.
transducer (Transducer) – Transducer parameters.
rp (Optional[float]) – Parallel damping resistance. If None, uses transducer.rp. If still None, open circuit is assumed.
di0 (float) – Initial derivative i’(0) in A/s.
d2i0 (Optional[float]) – Initial second derivative i’’(0) in A/s^2.

Returns:

Current i(t).

Return type:

float

transientbvd.deactivation.deactivation_potential(transducer, resistance_range=(10, 5000))[source]

Evaluate deactivation performance over a resistance range.

This helper computes: - the “no-Rp” decay time estimate (tau_no_rp = 2*Ls/Rs) - the optimum parallel resistance Rp within the provided range - the corresponding decay time with Rp - absolute and relative improvement vs. no-Rp

Parameters:

transducer (Transducer) – Transducer parameters (Rs, Ls, Cs, C0).
resistance_range (Tuple[float, float], optional) – Search interval (min_Rp, max_Rp) in ohms. Defaults to (10, 5000).

Returns:

(optimal_resistance, tau_with_rp, delta_time, percentage_improvement) where: - optimal_resistance is Rp in ohms - tau_with_rp is the decay time in seconds using optimal_resistance - delta_time = tau_no_rp - tau_with_rp in seconds - percentage_improvement = 100 * delta_time / tau_no_rp

Return type:

Tuple[float, float, float, float]

transientbvd.deactivation.deactivation_tau(transducer, rp=None)[source]

Calculate the decay time (τ) for a given transducer with an optional parallel resistance (rp).

Parameters:

transducer (Transducer) – The transducer object containing the necessary circuit parameters.
rp (Optional[float], default=None) – Parallel resistance in ohms. If None, decay time is calculated without rp.

Returns:

Decay time (τ) in seconds.

Return type:

float

Raises:

ValueError – If any transducer parameter (rs, ls, cs, c0) is not positive or if rp is non-positive.

Notes

When rp is not provided, the decay time is calculated using the formula: τ = 2 * ls / rs (approximating the deactivation condition).
When rp is provided, the decay time is determined using the eigenvalues of the characteristic polynomial.

transientbvd.deactivation.deactivation_two_tau(transducer, rp=None)[source]

Calculate twice the decay time (2τ) for a given transducer with an optional parallel resistance (rp).

Parameters:

transducer (Transducer) – The transducer object containing the necessary circuit parameters.
rp (Optional[float], default=None) – Parallel resistance in ohms. If None, decay time is calculated without rp.

Returns:

Twice the decay time (2τ) in seconds.

Return type:

float

Raises:

ValueError – If any transducer parameter (rs, ls, cs, c0) is not positive or if rp is non-positive.

Notes

When rp is not provided, the decay time is calculated using the formula: 2τ = 4 * ls / rs (approximating the deactivation condition).
When rp is provided, the decay time is determined using the eigenvalues of the characteristic polynomial.

transientbvd.deactivation.optimum_resistance(transducer, resistance_range=(10, 10000))[source]

Calculate the optimal parallel resistance (highest damping) for the transient response in a transducer modeled by the Butterworth-Van Dyke (BVD) equivalent circuit using numerical optimization.

Parameters:

transducer (Transducer) – The transducer object containing the necessary circuit parameters.
resistance_range (Tuple[float, float], default=(10, 10,000)) – A tuple representing the lower and upper bounds for resistance (in ohms) to evaluate.

Returns:

A tuple containing: - The optimal resistance value in ohms that minimizes the decay time. - The corresponding decay time in seconds.

Return type:

Tuple[float, float]

Raises:

ValueError – If any transducer parameter (rs, ls, cs, c0) is not positive or if resistance bounds are invalid.

transientbvd.deactivation.print_deactivation_potential(transducer, resistance_range=(10, 5000))[source]

Display the results of deactivation_potential, including decay times and speed improvement.

This function evaluates how the deactivation transient response improves when introducing an optimal parallel resistance (Rp). It prints decay times with and without Rp, as well as the absolute and percentage improvements.

Parameters:

transducer (Transducer) – The transducer object containing the necessary circuit parameters.
resistance_range (Tuple[float, float], optional) – The range of resistance values (in ohms) to evaluate for optimal damping. Default is (10, 5000) Ω.

Return type:

None

Activation (activation.py)

TransientBVD - Activation Transient Analysis

This module contains functions for analyzing the activation transient response of resonant circuits modeled by the Butterworth-Van Dyke (BVD) equivalent circuit.

transientbvd.activation.activation_4tau(transducer, ucw, ub=None, t_sw=None)[source]

Calculate the time at which the oscillation amplitude first reaches 98.2% of the steady-state current in the activation scenario.

Parameters:

transducer (Transducer) – The transducer containing the circuit parameters.
ucw (float) – Continuous-wave voltage amplitude in volts.
ub (float, optional) – Overboost voltage amplitude in volts.
t_sw (float, optional) – Switching time in seconds.

Returns:

The 4τ time in seconds.

Return type:

float

transientbvd.activation.activation_current(t, transducer, ucw, ub=None, t_sw=None)[source]

Compute the transient current response for an activation BVD model.

Parameters:

t (float) – Time in seconds. If np.inf is provided, this returns the steady-state current (U_cw / R_s).
transducer (Transducer) – The transducer containing the circuit parameters.
ucw (float) – Operating (continuous-wave) voltage amplitude in volts. Must be > 0.
ub (float, optional) – Overboost voltage amplitude in volts. If provided, must be > 0 and > U_cw.
t_sw (float, optional) – Switching time in seconds. If provided, must be > 0. If not provided but ub is given, it is computed via switching_time.

Returns:

The transient current at time t.

Return type:

float

transientbvd.activation.activation_potential(transducer, ucw, ub)[source]

Evaluate the potential improvement in transient response time when using overboosting in the activation scenario.

Parameters:

transducer (Transducer) – The transducer containing the circuit parameters.
ucw (float) – Continuous-wave voltage amplitude in volts.
ub (float) – Overboost voltage amplitude in volts.

Returns:

(t_sw, tau_no_boost, tau_with_boost, delta_time, percentage_improvement).

Return type:

Tuple[float, float, float, float, float]

transientbvd.activation.print_activation_potential(transducer, ucw, ub)[source]

Pretty print the results of the activation overboosting potential analysis.

Parameters:

transducer (Transducer) – The transducer containing the circuit parameters.
ucw (float) – Continuous-wave voltage amplitude in volts.
ub (float) – Overboost voltage amplitude in volts.

Return type:

None

transientbvd.activation.switching_time(transducer, ub, ucw)[source]

Calculate the switching time for the transient response in the activation scenario.

Parameters:

transducer (Transducer) – The transducer containing the circuit parameters.
ub (float) – Overboost voltage amplitude in volts.
ucw (float) – Continuous-wave voltage amplitude in volts.

Returns:

Switching time in seconds.

Return type:

float

Transducer Class (transducer.py)

TransientBVD - Transducer Model

This module defines the Transducer class, which represents an ultrasound transducer with predefined parameters. The transducer stores electrical circuit parameters and additional metadata such as the manufacturer and resonance frequency.

class transientbvd.transducer.Transducer(rs, ls, cs, c0, rp=None, name='Unknown', manufacturer=None)[source]

Bases: object

Represents an ultrasound transducer described by a BVD equivalent circuit.

Parameters:

rs (float) – Series resistance in ohms. Must be positive.
ls (float) – Inductance in henries. Must be positive.
cs (float) – Series capacitance in farads. Must be positive.
c0 (float) – Parallel capacitance in farads. Must be positive.
rp (Optional[float], optional) – Parallel resistance in ohms. If provided, must be positive.
name (str, optional) – Human-readable transducer name.
manufacturer (Optional[str], optional) – Manufacturer name.

c0: float

cs: float

property frequency: float

Compute the resonance frequency dynamically.

Returns:: Resonance frequency in Hz.
Return type:: float

ls: float

manufacturer: str | None = None

name: str = 'Unknown'

rp: float | None = None

rs: float

set_manufacturer(manufacturer)[source]

Set the manufacturer of the transducer.

Parameters:: manufacturer (str) – The manufacturer name.
Returns:: The updated transducer instance (supports method chaining).
Return type:: Transducer

set_name(name)[source]

Set the transducer’s name.

Parameters:: name (str) – The name to assign to the transducer.
Returns:: The updated transducer instance (supports method chaining).
Return type:: Transducer

set_rp(rp)[source]

Set the parallel resistance (rp) value.

Parameters:: rp (float) – Parallel resistance in ohms. Must be positive.
Returns:: The updated transducer instance (supports method chaining).
Return type:: Transducer
Raises:: ValueError – If rp is not positive.

transientbvd.transducer.load_measured_transducers(json_file=None)[source]

Backwards-compatible alias for load_transducers().

Parameters:: json_file (str | Path | None)
Return type:: Dict[str, Transducer]

transientbvd.transducer.load_transducers(json_file=None)[source]

Load transducer data and create Transducer objects.

Parameters:: json_file (Optional[Union[str, Path]]) – Path to a JSON file. If None: - will try env var TRANSIENTBVD_TRANSDUCERS_JSON - otherwise loads the bundled default database.
Returns:: Dictionary keyed by transducer name.
Return type:: Dict[str, Transducer]

transientbvd.transducer.predefined_transducers(json_file=None)[source]

Get a dictionary of all predefined transducers.

Parameters:: json_file (Optional[Union[str, Path]]) – Optional JSON database path override.
Returns:: Dictionary mapping transducer names to Transducer objects.
Return type:: Dict[str, Transducer]

transientbvd.transducer.select_transducer(name, json_file=None)[source]

Retrieve a predefined transducer by its name.

Parameters:

name (str) – Name of the transducer to retrieve.
json_file (Optional[Union[str, Path]]) – Optional JSON database path override.

Raises:

ValueError – If the transducer name does not exist.

Return type:

Transducer

Utility Functions (utils.py)

TransientBVD - Utility Functions

This module provides general-purpose utility functions for transient analysis of resonant circuits modeled by the Butterworth-Van Dyke (BVD) equivalent circuit.

Functions include resonance frequency calculation, polynomial root solving, and other numerical methods used throughout the TransientBVD package.

transientbvd.utils.resonance_frequency(ls: float, cs: float) → float[source]

Calculate the resonance frequency of a system based on the Butterworth-Van Dyke (BVD) model.

The resonance frequency is given by:

\[f_r = \frac{1}{2\pi\sqrt{L_s C_s}},\]

where \(L_s\) is the motional inductance and \(C_s\) is the motional capacitance.

Parameters:

ls (float, optional) – Motional inductance in henries.
cs (float, optional) – Motional capacitance in farads.

Returns:

The resonance frequency in hertz.

Return type:

float

Notes

Only ls and cs are used in the calculation.

Raises:: ValueError – If required parameters are missing or invalid.

transientbvd.utils.roots(rs: float, ls: float, cs: float, c0: float, rp: float | None = None) → List[complex][source]

Calculate the roots of the characteristic polynomial for the transient response of a system modeled by the Butterworth-Van Dyke (BVD) equivalent circuit.

IMPORTANT TERMINATION SEMANTICS (matches “MOSFET opens”): - rp is None => open circuit termination (Rp → ∞) - rp is +inf => open circuit termination (Rp → ∞) - rp is finite positive => explicit parallel damping resistor

For open circuit (Rp → ∞), the cubic has a0 = 0, which introduces a root at 0. That is expected for this terminal condition; the transient decay then comes from the oscillatory pair’s negative real part (≈ -Rs/(2Ls)).

Returns:: Roots (complex) of: s^3 + a2*s^2 + a1*s + a0 = 0
Return type:: List[complex]
Raises:: ValueError – If parameters are missing or non-positive, or rp is non-positive when finite.