Examples

Below are various example scripts from the TransientBVD/examples directory, demonstrating how to use TransientBVD in different scenarios. Each snippet is embedded here for convenient reference.

Basic Example

A minimal script showing how to import TransientBVD and call a simple method.

# basic_example.py
from transientbvd import (
    print_deactivation_potential,
    predefined_transducers,
    select_transducer,
)
from transientbvd.activation import print_activation_potential

# Step 1: List all predefined transducers
print("Available predefined transducers:")
transducer_names = predefined_transducers()
for name in transducer_names:
    print(f"  - {name}")

print("\n")

# Step 2: Select a transducer by name and print its details
selected_name = "Custom"  # Change to another name if desired
transducer = select_transducer(selected_name)

# Use __str__ to print transducer details
print(f"Details of selected transducer:\n{transducer}")


# Deactivation: Define resistance range for deactivation potential analysis
resistance_range = (1, 10000)  # Range of resistances to evaluate in ohms
print_deactivation_potential(transducer, resistance_range)

# Activation: Use a boost voltage of 20V and a continuous wave voltage of 10V
print_activation_potential(transducer, ucw=20.0, ub=40)

Basic Predefined Transducer Example

Demonstrates creating a predefined transducer object and using library methods.

from transientbvd import predefined_transducers, select_transducer

# Step 1: List all predefined transducers
print("Available predefined transducers:")
transducer_names = predefined_transducers()
for name in transducer_names:
    print(f"  - {name}")

print("\n")

# Step 2: Select a transducer by name and print its details
selected_name = "SMBLTD45F40H_1"  # Change to another name if desired
transducer = select_transducer(selected_name)

# Use __str__ to print transducer details
print(f"Details of selected transducer:\n{transducer}")

# Step 3: Print the equivalent circuit parameters using built-in pretty print
print("\nEquivalent Circuit Parameters:")
print(transducer)

# Step 4: Access individual parameters (since Transducer inherits EquivalentCircuitParams)
print("\nAccessing individual circuit parameters:")
print(f"  rs = {transducer.rs:.4f} Ω")
print(f"  ls = {transducer.ls:.6f} H")
print(f"  cs = {transducer.cs:.2e} F")
print(f"  c0 = {transducer.c0:.2e} F")

# If the transducer has an optional parallel resistance (rp)
if transducer.rp is not None:
    print(f"  rp = {transducer.rp:.2f} Ω")

# Step 5: Print resonance frequency
print(f"\nResonance Frequency: {transducer.frequency:.2f} Hz")

Deactivation Time Example

Shows how to compute deactivation time (τ) in different conditions for deactivation.

from transientbvd import select_transducer, deactivation_tau, deactivation_two_tau

# Step 1: Select a predefined transducer
selected_name = "SMBLTD45F28H_28kHz"
transducer = select_transducer(selected_name)
print(f"Selected Transducer:\n{transducer}\n")

# Step 2: Calculate τ (tau) and 2τ (two tau) without parallel resistance (rp=None)
tau_no_rp = deactivation_tau(transducer)
two_tau_no_rp = deactivation_two_tau(transducer)

print("Decay Times without Parallel Resistance (rp=None):")
print(f"  τ (Tau): {tau_no_rp:.6f} s ({tau_no_rp * 1e3:.2f} ms)")
print(f"  2τ (Two Tau): {two_tau_no_rp:.6f} s ({two_tau_no_rp * 1e3:.2f} ms)\n")

# Step 3: Calculate τ (tau) and 2τ (two tau) with a specified parallel resistance (rp=950 Ω)
rp = 900  # Parallel resistance in ohms
tau_with_rp = deactivation_tau(transducer, rp)
two_tau_with_rp = deactivation_two_tau(transducer, rp)

print(f"Decay Times with Parallel Resistance (rp={rp} Ω):")
print(f"  τ (Tau): {tau_with_rp:.6f} s ({tau_with_rp * 1e3:.2f} ms)")
print(f"  2τ (Two Tau): {two_tau_with_rp:.6f} s ({two_tau_with_rp * 1e3:.2f} ms)")

Deactivation Time Over Rp Example

Explores how deactivation time changes over various parallel resistance values (Rp) in the deactivation scenario.

import numpy as np
import matplotlib.pyplot as plt
from transientbvd import select_transducer, deactivation_two_tau

# Step 1: Select a predefined transducer
selected_name = "SMBLTD45F28H_28kHz"
transducer = select_transducer(selected_name)
print(f"Selected Transducer:\n{transducer}\n")

# Step 2: Define the range of resistance values
rp_values = np.logspace(1, 4, 100)  # Logarithmic scale from 10 Ω to 10,000 Ω

# Step 3: Calculate decay times for each resistance value
decay_times = [deactivation_two_tau(transducer, rp) for rp in rp_values]

# Step 4: Plot Decay Time vs Resistance
plt.figure(figsize=(8, 6))
plt.plot(rp_values, decay_times, label="Decay Time (2τ)", linewidth=2)
plt.xscale("log")
plt.yscale("log")
plt.xlabel("Parallel Resistance (Rp) [Ω]")
plt.ylabel("Decay Time (2τ) [s]")
plt.title("Decay Time vs Parallel Resistance")
plt.grid(True, which="both", linestyle="--", linewidth=0.5)
plt.legend()
plt.show()

Optimum Resistance Example

Uses the library’s optimization routine to find the best Rp for minimal deactivation time.

from transientbvd import optimum_resistance, select_transducer

# Step 1: Select a predefined transducer
selected_name = "SMBLTD45F28H_28kHz"
transducer = select_transducer(selected_name)
print(f"Selected Transducer:\n{transducer}\n")

# Step 2: Define a resistance range
resistance_range = (10, 5000)  # Resistance range in ohms

# Step 3: Calculate the optimum resistance
optimal_resistance, minimal_decay_time = optimum_resistance(
    transducer, resistance_range
)

# Step 4: Display the results
print("Optimal Resistance Calculation:")
print(f"  Resistance Range: {resistance_range[0]} Ω to {resistance_range[1]} Ω")
print(f"  Optimal Resistance: {optimal_resistance:.2f} Ω")
print(
    f"  Minimal Decay Time: {minimal_decay_time:.6f} s ({minimal_decay_time * 1e3:.2f} ms)"
)

Plot Activation Current Example

Plots the transient current response under an activation scenario with overboost.

"""
activation_current_plot_example.py

This script plots the activation transient current response from the
TransientBVD library. It compares:
1. The overboost approach (using switching time).
2. The default approach (only continuous-wave voltage).
"""

import numpy as np
import matplotlib.pyplot as plt
from transientbvd import select_transducer
from transientbvd.activation import activation_current, activation_4tau


def plot_activation_current(
    timestamps: list[float],
    transducer,
    ucw: float,
    ub: float | None = None,
    t_sw: float | None = None,
) -> None:
    """
    Plot the transient current response over time for an activation BVD model.

    If 'ub' is given, plots two lines:
      1) Overboost approach (from 0 to t_sw with Ub, then switching to Ucw).
      2) Default approach (only Ucw from t=0).
    Adds lines for:
      - Steady-state current (horizontal)
      - 4τ time for both the overboosted and non-overboosted scenarios (vertical lines)
      - Switching time t_sw if provided.

    Parameters
    ----------
    timestamps : list[float]
        Time points (seconds) for evaluating the current.
    transducer : Transducer
        The transducer object containing the equivalent circuit parameters.
    ucw : float
        Continuous-wave voltage (volts).
    ub : float, optional
        Overboost voltage (volts). If None, no overboost is applied.
    t_sw : float, optional
        Switching time (seconds). If None, and 'ub' is given, an optimal switching time
        can be calculated internally by `switching_time`.
    """
    # 1) Evaluate currents for the overboost approach (if ub is given) or default approach
    currents_overboost = [
        activation_current(t, transducer, ucw, ub, t_sw) for t in timestamps
    ]

    # 2) Plot results
    plt.figure(figsize=(8, 5))
    label_overboost = (
        "Transient Current using overboost"
        if ub is not None
        else "Transient Current (No Overboost)"
    )
    plt.plot(timestamps, currents_overboost, label=label_overboost, color="b")

    # 3) Add the steady-state current reference
    steady_state_current = ucw / transducer.rs
    plt.axhline(
        y=steady_state_current, color="r", linestyle="--", label="Steady-State Current"
    )

    # 4) If ub is specified, also plot the scenario without any overboost
    if ub is not None:
        # Currents if only UCW is applied from t=0
        currents_no_boost = [activation_current(t, transducer, ucw) for t in timestamps]
        plt.plot(
            timestamps,
            currents_no_boost,
            label="Transient Current (Only U_cw)",
            color="orange",
            linestyle="dashed",
        )

    # 5) Plot the 4τ time for the overboost approach (or single approach if no ub)
    t_4tau_overboost = activation_4tau(transducer, ucw, ub, t_sw)
    plt.axvline(
        x=t_4tau_overboost, color="black", linestyle="--", label="4τ (Overboost)"
    )

    # 6) If ub is specified, also show the 4τ time for no overboost
    if ub is not None:
        t_4tau_no_boost = activation_4tau(transducer, ucw)
        plt.axvline(
            x=t_4tau_no_boost, color="g", linestyle="dashed", label="4τ (Only U_cw)"
        )

    # 7) If switching time is given, visualize it
    if t_sw is not None:
        plt.axvline(x=t_sw, color="black", linestyle="solid", label="Switching Time")

    # 8) Final plot formatting
    plt.xlabel("Time (s)")
    plt.ylabel("Current (A)")
    plt.title("Activation Transient Current Response Example")
    plt.legend()
    plt.grid()
    plt.show()


def main():
    """
    Demonstrates usage of the 'plot_activation_current' function.
    """
    # Step 1: Select a predefined transducer
    selected_name = "SMBLTD45F40H_1"
    transducer = select_transducer(selected_name)
    print(f"Selected Transducer:\n{transducer}\n")

    # Example parameters (modify as needed):
    ucw = 40.0
    ub = 60.0

    # Example timestamps
    timestamps = np.linspace(0, 0.020, 10000).tolist()

    # Optional switching time
    t_sw = 0.003  # 3 ms

    # Run the plotting function
    plot_activation_current(
        timestamps=timestamps, transducer=transducer, ucw=ucw, ub=ub, t_sw=t_sw
    )


if __name__ == "__main__":
    main()

Regular Decay Example

Illustrates “regular” or default decay behavior without special damping or overboost.

import pandas as pd
from transientbvd import select_transducer

# Define the transducer models and their numbers
transducer_info = {
    1: "Custom",
    2: "8AF200184",
    3: "GB-4540-4SH",
    4: "SMBLTD45F40H_1",
    5: "MA40S4S",
    6: "SMBLTD45F28H_28kHz",
}

# Data storage for export
data = []

# Process each transducer
for number, name in transducer_info.items():
    try:
        # Load the predefined transducer
        transducer = select_transducer(name)

        # Calculate decay times without using Rp
        tau_no_rp = 2 * transducer.ls / transducer.rs
        two_tau_no_rp = 2 * tau_no_rp

        # Store data for export
        data.append(
            {
                "Transducer Number": number,
                "Model": name,
                "Rs (Ω)": transducer.rs,
                "Ls (mH)": transducer.ls * 1e3,  # Convert H to mH
                "Cs (pF)": transducer.cs * 1e12,  # Convert F to pF
                "C0 (pF)": transducer.c0 * 1e12,  # Convert F to pF
                "Two Tau (ms)": two_tau_no_rp * 1e3,  # Convert s to ms
            }
        )

    except Exception as e:
        print(f"Error processing {name}: {e}")

# Export data to CSV
export_df = pd.DataFrame(data)
export_df.to_csv("transducer_two_tau.csv", index=False)

print("Regular decay data exported to transducer_two_tau.csv")

Results Saving Example

Showcases how to capture and save computation results (e.g., to CSV or JSON).

import pandas as pd
import numpy as np
from transientbvd import Transducer, deactivation_tau

# Step 1: Create a transducer directly in the code
transducer = (
    Transducer(
        rs=24.764,  # Series resistance in ohms
        ls=38.959e-3,  # Inductance in henries
        cs=400.33e-12,  # Series capacitance in farads
        c0=3970.1e-12,  # Parallel capacitance in farads
    )
    .set_name("ExampleTransducer")
    .set_manufacturer("Example Manufacturer")
)

print("Transducer used for analysis:")
print(transducer)

# Step 2: Perform decay analysis over a resistance range
resistance_range = np.linspace(10, 1000, 50)  # 50 points between 10 and 1000 ohms
decay_times = [deactivation_tau(transducer, rp=rp) for rp in resistance_range]

# Create a DataFrame to store the results
decay_df = pd.DataFrame(
    {"Resistance (Ohms)": resistance_range, "Decay Time (s)": decay_times}
)

# Print the first few rows of the analysis
print("\nDecay Analysis Results:")
print(decay_df.head())

# Step 3: Save the results to a CSV file
output_file = "decay_analysis_results.csv"
decay_df.to_csv(output_file, index=False)
print(f"\nDecay analysis results saved to {output_file}.")