ee-toolkit 0.0.2__py3-none-any.whl

ee_toolkit/opamp.py

@@ -0,0 +1,180 @@
+"""
+Op-amp circuit calculations.
+
+Amplifiers
+----------
+  Non-inverting:  Gain = 1 + Rf / R1
+  Inverting:      Gain = -(Rf / R1)
+
+Integrator  (inverting)
+-----------------------
+  Corner frequency:  f = 1 / (2π · R · C)
+  Gain at frequency: |A(f)| = 1 / (2π · f · R · C)   [no DC description – ideal]
+
+Differentiator  (inverting)
+---------------------------
+  Corner frequency:  f = 1 / (2π · R · C)
+  Gain at frequency: |A(f)| = 2π · f · R · C
+"""
+import math
+import click
+from .units import parse_si, fmt_si
+
+
+# ---------------------------------------------------------------------------
+# Pure math helpers
+# ---------------------------------------------------------------------------
+
+def noninv_gain(rf: float, r1: float) -> float:
+    """Non-inverting amplifier closed-loop gain."""
+    return 1.0 + rf / r1
+
+
+def inv_gain(rf: float, r1: float) -> float:
+    """Inverting amplifier closed-loop gain (negative = phase-inverting)."""
+    return -(rf / r1)
+
+
+def integrator_corner(r: float, c: float) -> float:
+    """Integrator corner frequency (Hz) — same as RC cutoff."""
+    return 1.0 / (2.0 * math.pi * r * c)
+
+
+def integrator_gain_at(r: float, c: float, freq: float) -> float:
+    """Ideal integrator magnitude gain at *freq* Hz."""
+    return 1.0 / (2.0 * math.pi * freq * r * c)
+
+
+def differentiator_corner(r: float, c: float) -> float:
+    """Differentiator corner frequency (Hz)."""
+    return 1.0 / (2.0 * math.pi * r * c)
+
+
+def differentiator_gain_at(r: float, c: float, freq: float) -> float:
+    """Ideal differentiator magnitude gain at *freq* Hz."""
+    return 2.0 * math.pi * freq * r * c
+
+
+# ---------------------------------------------------------------------------
+# Click command group
+# ---------------------------------------------------------------------------
+
+@click.group()
+def opamp_group():
+    """Op-amp circuit calculations (gain, integrator, differentiator)."""
+
+
+# ── Non-inverting amplifier ─────────────────────────────────────────────────
+@opamp_group.command('noninv')
+@click.option('--rf', 'rf_str', required=True, metavar='VALUE',
+              help='Feedback resistor, e.g. 100k')
+@click.option('--r1', 'r1_str', required=True, metavar='VALUE',
+              help='Input/ground resistor, e.g. 10k')
+def cmd_noninv(rf_str, r1_str):
+    """Non-inverting amplifier closed-loop gain.
+
+    \b
+    Gain = 1 + Rf / R1
+
+    Example:
+      ee-calc opamp noninv --rf 100k --r1 10k   →  Gain = +11
+    """
+    rf = parse_si(rf_str)
+    r1 = parse_si(r1_str)
+    g = noninv_gain(rf, r1)
+    click.echo("Non-inverting amplifier")
+    click.echo(f"  Rf  = {fmt_si(rf, 'Ω')}")
+    click.echo(f"  R1  = {fmt_si(r1, 'Ω')}")
+    click.echo(f"  Gain = 1 + Rf/R1 = {g:.6g}  ({20*math.log10(abs(g)):.2f} dB)")
+
+
+# ── Inverting amplifier ─────────────────────────────────────────────────────
+@opamp_group.command('inv')
+@click.option('--rf', 'rf_str', required=True, metavar='VALUE',
+              help='Feedback resistor, e.g. 100k')
+@click.option('--r1', 'r1_str', required=True, metavar='VALUE',
+              help='Input resistor, e.g. 10k')
+def cmd_inv(rf_str, r1_str):
+    """Inverting amplifier closed-loop gain.
+
+    \b
+    Gain = -(Rf / R1)
+
+    Example:
+      ee-calc opamp inv --rf 100k --r1 10k   →  Gain = -10
+    """
+    rf = parse_si(rf_str)
+    r1 = parse_si(r1_str)
+    g = inv_gain(rf, r1)
+    click.echo("Inverting amplifier")
+    click.echo(f"  Rf   = {fmt_si(rf, 'Ω')}")
+    click.echo(f"  R1   = {fmt_si(r1, 'Ω')}")
+    click.echo(f"  Gain = -(Rf/R1) = {g:.6g}  ({20*math.log10(abs(g)):.2f} dB)")
+
+
+# ── Integrator ──────────────────────────────────────────────────────────────
+@opamp_group.command('integrator')
+@click.option('--r', 'r_str', required=True, metavar='VALUE',
+              help='Input resistor, e.g. 10k')
+@click.option('--c', 'c_str', required=True, metavar='VALUE',
+              help='Feedback capacitor, e.g. 100n')
+@click.option('--freq', 'freq_str', default=None, metavar='VALUE',
+              help='Optional: evaluate gain magnitude at this frequency, e.g. 1k')
+def cmd_integrator(r_str, c_str, freq_str):
+    """Inverting op-amp integrator.
+
+    \b
+    Corner frequency:  f₀ = 1 / (2π · R · C)
+    Gain magnitude:   |A(f)| = 1 / (2π · f · R · C)  =  f₀ / f
+
+    Example:
+      ee-calc opamp integrator --r 10k --c 100n
+      ee-calc opamp integrator --r 10k --c 100n --freq 500
+    """
+    r = parse_si(r_str)
+    c = parse_si(c_str)
+    f0 = integrator_corner(r, c)
+    click.echo("Inverting integrator")
+    click.echo(f"  R  = {fmt_si(r, 'Ω')}")
+    click.echo(f"  C  = {fmt_si(c, 'F')}")
+    click.echo(f"  Corner frequency f₀ = {fmt_si(f0, 'Hz')}")
+    click.echo(f"  (Unity-gain frequency where |A| = 1)")
+    if freq_str:
+        freq = parse_si(freq_str)
+        gain = integrator_gain_at(r, c, freq)
+        click.echo(f"\n  At f = {fmt_si(freq, 'Hz')}:")
+        click.echo(f"    |A| = {gain:.6g}  ({20*math.log10(gain):.2f} dB)")
+
+
+# ── Differentiator ──────────────────────────────────────────────────────────
+@opamp_group.command('differentiator')
+@click.option('--r', 'r_str', required=True, metavar='VALUE',
+              help='Feedback resistor, e.g. 10k')
+@click.option('--c', 'c_str', required=True, metavar='VALUE',
+              help='Input capacitor, e.g. 100n')
+@click.option('--freq', 'freq_str', default=None, metavar='VALUE',
+              help='Optional: evaluate gain magnitude at this frequency, e.g. 1k')
+def cmd_differentiator(r_str, c_str, freq_str):
+    """Inverting op-amp differentiator.
+
+    \b
+    Corner frequency:  f₀ = 1 / (2π · R · C)
+    Gain magnitude:   |A(f)| = 2π · f · R · C  =  f / f₀
+
+    Example:
+      ee-calc opamp differentiator --r 10k --c 100n
+      ee-calc opamp differentiator --r 10k --c 100n --freq 2k
+    """
+    r = parse_si(r_str)
+    c = parse_si(c_str)
+    f0 = differentiator_corner(r, c)
+    click.echo("Inverting differentiator")
+    click.echo(f"  R  = {fmt_si(r, 'Ω')}")
+    click.echo(f"  C  = {fmt_si(c, 'F')}")
+    click.echo(f"  Corner frequency f₀ = {fmt_si(f0, 'Hz')}")
+    click.echo(f"  (Unity-gain frequency where |A| = 1)")
+    if freq_str:
+        freq = parse_si(freq_str)
+        gain = differentiator_gain_at(r, c, freq)
+        click.echo(f"\n  At f = {fmt_si(freq, 'Hz')}:")
+        click.echo(f"    |A| = {gain:.6g}  ({20*math.log10(gain):.2f} dB)")

ee_toolkit/oscillator.py

@@ -0,0 +1,107 @@
+"""
+Oscillator resonance frequency calculations.
+
+LC oscillator / tank circuit:
+  f₀ = 1 / (2π · √(L · C))
+
+Colpitts / Hartley (two reactive elements in series → C_total or L_total):
+  Colpitts:  C_eff = (C1 · C2) / (C1 + C2)  → f₀ = 1 / (2π · √(L · C_eff))
+  Hartley:   L_eff = L1 + L2                 → f₀ = 1 / (2π · √(L_eff · C))
+"""
+import math
+import click
+from .units import parse_si, fmt_si
+from .filters import lc_resonance
+
+
+# ---------------------------------------------------------------------------
+# Click command group
+# ---------------------------------------------------------------------------
+
+@click.group()
+def oscillator_group():
+    """Oscillator resonance frequency calculations (LC, Colpitts, Hartley)."""
+
+
+@oscillator_group.command('lc')
+@click.option('--l', 'l_str', required=True, metavar='VALUE',
+              help='Inductance, e.g. 10u, 1m')
+@click.option('--c', 'c_str', required=True, metavar='VALUE',
+              help='Capacitance, e.g. 100p, 10n')
+def cmd_lc(l_str, c_str):
+    """LC tank oscillator resonance frequency.
+
+    \b
+    f₀ = 1 / (2π · √(L · C))
+
+    Example:
+      ee-calc oscillator lc --l 10u --c 100p
+    """
+    l = parse_si(l_str)
+    c = parse_si(c_str)
+    f = lc_resonance(l, c)
+    click.echo("LC oscillator")
+    click.echo(f"  L  = {fmt_si(l, 'H')}")
+    click.echo(f"  C  = {fmt_si(c, 'F')}")
+    click.echo(f"  f₀ = {fmt_si(f, 'Hz')}")
+    click.echo(f"  ω₀ = {2*math.pi*f:.6g} rad/s")
+
+
+@oscillator_group.command('colpitts')
+@click.option('--l', 'l_str', required=True, metavar='VALUE',
+              help='Inductance, e.g. 10u')
+@click.option('--c1', 'c1_str', required=True, metavar='VALUE',
+              help='Capacitor 1, e.g. 100p')
+@click.option('--c2', 'c2_str', required=True, metavar='VALUE',
+              help='Capacitor 2, e.g. 100p')
+def cmd_colpitts(l_str, c1_str, c2_str):
+    """Colpitts oscillator resonance frequency.
+
+    \b
+    C_eff = (C1 · C2) / (C1 + C2)
+    f₀    = 1 / (2π · √(L · C_eff))
+
+    Example:
+      ee-calc oscillator colpitts --l 10u --c1 100p --c2 100p
+    """
+    l  = parse_si(l_str)
+    c1 = parse_si(c1_str)
+    c2 = parse_si(c2_str)
+    c_eff = (c1 * c2) / (c1 + c2)
+    f = lc_resonance(l, c_eff)
+    click.echo("Colpitts oscillator")
+    click.echo(f"  L     = {fmt_si(l, 'H')}")
+    click.echo(f"  C1    = {fmt_si(c1, 'F')}")
+    click.echo(f"  C2    = {fmt_si(c2, 'F')}")
+    click.echo(f"  C_eff = {fmt_si(c_eff, 'F')}  (series combination)")
+    click.echo(f"  f₀    = {fmt_si(f, 'Hz')}")
+
+
+@oscillator_group.command('hartley')
+@click.option('--l1', 'l1_str', required=True, metavar='VALUE',
+              help='Inductor 1, e.g. 5u')
+@click.option('--l2', 'l2_str', required=True, metavar='VALUE',
+              help='Inductor 2, e.g. 5u')
+@click.option('--c', 'c_str', required=True, metavar='VALUE',
+              help='Capacitance, e.g. 100p')
+def cmd_hartley(l1_str, l2_str, c_str):
+    """Hartley oscillator resonance frequency.
+
+    \b
+    L_eff = L1 + L2
+    f₀    = 1 / (2π · √(L_eff · C))
+
+    Example:
+      ee-calc oscillator hartley --l1 5u --l2 5u --c 100p
+    """
+    l1 = parse_si(l1_str)
+    l2 = parse_si(l2_str)
+    c  = parse_si(c_str)
+    l_eff = l1 + l2
+    f = lc_resonance(l_eff, c)
+    click.echo("Hartley oscillator")
+    click.echo(f"  L1    = {fmt_si(l1, 'H')}")
+    click.echo(f"  L2    = {fmt_si(l2, 'H')}")
+    click.echo(f"  L_eff = {fmt_si(l_eff, 'H')}  (series combination)")
+    click.echo(f"  C     = {fmt_si(c, 'F')}")
+    click.echo(f"  f₀    = {fmt_si(f, 'Hz')}")

ee_toolkit/resistor.py

@@ -0,0 +1,258 @@
+"""
+Resistor series / parallel combination calculator.
+
+Series:    R_total = R1 + R2 + … + Rn
+Parallel:  1/R_total = 1/R1 + 1/R2 + … + 1/Rn
+
+The CLI command accepts one or more --sg (series group) options.
+Each --sg VALUE VALUE … is treated as resistors wired in parallel.
+Multiple --sg groups are then summed in series.
+
+Example
+-------
+Two 10 kΩ in parallel, in series with a 4.7 kΩ:
+
+    ee-calc resistor combine --sg 10k 10k --sg 4.7k
+"""
+from __future__ import annotations
+from typing import List, Tuple
+from .eseries import all_values
+
+
+def parallel(*resistances: float) -> float:
+    """Return the equivalent resistance of *resistances* wired in parallel.
+
+    Raises ValueError if any resistance is zero (short circuit).
+    """
+    if any(r == 0.0 for r in resistances):
+        raise ValueError("A resistor value of 0 Ω creates a short circuit.")
+    return 1.0 / sum(1.0 / r for r in resistances)
+
+
+def series(*resistances: float) -> float:
+    """Return the equivalent resistance of *resistances* wired in series."""
+    return sum(resistances)
+
+
+def series_parallel_groups(groups: List[List[float]]) -> float:
+    """
+    Compute the total resistance of groups wired in series, where each
+    group is a list of resistors wired in parallel.
+
+    Parameters
+    ----------
+    groups : list of lists
+        Each inner list is a parallel group.  Groups are combined in series.
+
+    Returns
+    -------
+    float
+        Total equivalent resistance in Ω.
+    """
+    group_values = []
+    for g in groups:
+        if len(g) == 1:
+            group_values.append(g[0])
+        else:
+            group_values.append(parallel(*g))
+    return series(*group_values)
+
+
+def voltage_divider(
+    v_in: float,
+    v_out: float,
+    r_total_target: float,
+    series: str,
+    n_results: int = 5,
+) -> List[Tuple[float, float, float, float, float, float]]:
+    """
+    Find best voltage divider resistor pair (r1, r2) for a given E-series.
+    Returns: list of (r1, r2, actual_vout, err_vout_percent, actual_rtot, err_rtot_percent)
+    """
+    base_vals = all_values(series)
+    ratio = v_out / v_in
+    if ratio >= 1.0 or ratio <= 0.0:
+        raise ValueError("V_out must be strictly between 0 and V_in.")
+
+    multiplier = ratio / (1.0 - ratio)
+    r1_opt = r_total_target / (1.0 + multiplier)
+
+    # Restrict search space
+    lo, hi = r1_opt * 0.01, r1_opt * 100.0
+    r1_cands = [v for v in base_vals if lo <= v <= hi]
+
+    best_for_ratio = {}
+
+    for r1 in r1_cands:
+        r2_ideal = r1 * multiplier
+        # Find nearest 5 standard values for R2 for this R1
+        r2_sorted = sorted(base_vals, key=lambda v: abs(v - r2_ideal))
+        for r2 in r2_sorted[:5]:
+            act_v = v_in * r2 / (r1 + r2)
+            # bin identical ratios together
+            err_v_abs = round(abs(act_v - v_out) / v_out * 100, 8)
+
+            act_r = r1 + r2
+            err_r = abs(act_r - r_total_target) / r_total_target * 100.0
+
+            item = (
+                r1, r2, act_v,
+                (act_v - v_out) / v_out * 100.0,
+                act_r,
+                (act_r - r_total_target) / r_total_target * 100.0
+            )
+
+            # keep the decade-shifted pair that is closest to r_total_target
+            if err_v_abs not in best_for_ratio or err_r < abs(best_for_ratio[err_v_abs][5]):
+                best_for_ratio[err_v_abs] = item
+
+    results = list(best_for_ratio.values())
+    results.sort(key=lambda x: (abs(x[3]), abs(x[5])))
+    return results[:n_results]
+
+
+# ---------------------------------------------------------------------------
+# Click commands
+# ---------------------------------------------------------------------------
+import re
+import click
+from .units import parse_si, fmt_si
+
+
+class _SeriesGroupParam(click.ParamType):
+    """Custom Click parameter type that collects --sg arguments.
+
+    Accepts a string of whitespace- or comma-separated SI resistor values
+    (e.g. "10k 10k" or "10k,10k").  The option is declared with
+    multiple=True so it may appear several times on the command line.
+    """
+    name = "VALUES"
+
+    def convert(self, value, param, ctx):
+        tokens = re.split(r'[\s,]+', value.strip())
+        tokens = [t for t in tokens if t]
+        if not tokens:
+            self.fail("at least one resistor value is required.", param, ctx)
+        try:
+            return [parse_si(t) for t in tokens]
+        except ValueError as exc:
+            self.fail(str(exc), param, ctx)
+
+
+_SG = _SeriesGroupParam()
+
+
+@click.group()
+def resistor_group():
+    """Resistor combination calculations (series / parallel)."""
+
+
+@resistor_group.command('combine')
+@click.option(
+    '--sg', 'groups',
+    type=_SG,
+    multiple=True,
+    metavar='VALUES',
+    help=(
+        'Parallel group: a quoted, space- or comma-separated list of resistor '
+        'values (e.g. --sg "10k 10k").  Repeat --sg to wire groups in series.'
+    ),
+)
+def cmd_combine(groups):
+    """Series / parallel resistor combination.
+
+    \b
+    Each --sg group is treated as resistors wired IN PARALLEL.
+    Multiple --sg groups are combined IN SERIES with each other.
+
+    \b
+    Formulas:
+      Parallel:  1/R = 1/R1 + 1/R2 + …
+      Series:    R   = R1 + R2 + …
+
+    \b
+    Examples:
+      # Two 10 kΩ in parallel → 5 kΩ
+      ee-calc resistor combine --sg "10k 10k"
+
+      # Two 10 kΩ in parallel, then in series with 4.7 kΩ
+      ee-calc resistor combine --sg "10k 10k" --sg 4.7k
+
+      # Three groups in series, each with mixed values
+      ee-calc resistor combine --sg "1k 2k" --sg 470 --sg "3.3k 3.3k"
+    """
+    if not groups:
+        raise click.UsageError("At least one --sg group is required.")
+
+    # Compute and display
+    click.echo("Resistor combination")
+    click.echo("")
+
+    group_results: List[float] = []
+    for i, values in enumerate(groups, start=1):
+        if len(values) == 1:
+            r_eq = values[0]
+            click.echo(f"  Group {i} (series):   {fmt_si(r_eq, 'Ω')}")
+        else:
+            try:
+                r_eq = parallel(*values)
+            except ValueError as exc:
+                raise click.UsageError(str(exc)) from exc
+            parts = " ‖ ".join(fmt_si(v, 'Ω') for v in values)
+            click.echo(f"  Group {i} (parallel): {parts}  →  {fmt_si(r_eq, 'Ω')}")
+        group_results.append(r_eq)
+
+    total = series(*group_results)
+    click.echo("")
+    if len(group_results) > 1:
+        series_str = " + ".join(fmt_si(r, 'Ω') for r in group_results)
+        click.echo(f"  Total (series sum):  {series_str}")
+    click.echo(f"  R_total = {fmt_si(total, 'Ω')}")
+
+
+_SERIES_CHOICE = click.Choice(['E12', 'E24', 'E48', 'E96', 'E192'], case_sensitive=False)
+
+@resistor_group.command('divider')
+@click.option('--vin', 'vin_str', required=True, metavar='VALUE', help='Input voltage.')
+@click.option('--vout', 'vout_str', required=True, metavar='VALUE', help='Target output voltage.')
+@click.option('--ztot', 'ztot_str', required=True, metavar='VALUE', help='Target total impedance (R1 + R2), e.g. 10k.')
+@click.option('--series', default='E24', show_default=True, type=_SERIES_CHOICE, help='E-series to use.')
+@click.option('-n', 'n', default=5, show_default=True, help='Number of combinations to show.')
+def cmd_divider(vin_str, vout_str, ztot_str, series, n):
+    """Calculate voltage divider resistors.
+
+    \b
+    Finds the best R1 (top) and R2 (bottom) in the specified E-series
+    that provide the target output voltage, while keeping the sum
+    R1 + R2 close to the target total impedance.
+
+    \b
+    Formula:
+      V_out = V_in * (R2 / (R1 + R2))
+
+    \b
+    Example:
+      ee-calc resistor divider --vin 5 --vout 3.3 --ztot 10k --series E48
+    """
+    try:
+        v_in = parse_si(vin_str)
+        v_out = parse_si(vout_str)
+        r_tot = parse_si(ztot_str)
+        results = voltage_divider(v_in, v_out, r_tot, series, n)
+    except ValueError as exc:
+        raise click.UsageError(str(exc)) from exc
+
+    click.echo(f"Voltage Divider (series {series.upper()})")
+    click.echo(f"  V_in:  {fmt_si(v_in, 'V')}")
+    click.echo(f"  V_out: {fmt_si(v_out, 'V')} (target)")
+    click.echo(f"  Z_tot: {fmt_si(r_tot, 'Ω')} (target)")
+    click.echo("")
+    click.echo(f"{'Rank':<5} {'R1 (top)':<12} {'R2 (bot)':<12} {'V_out':<10} {'Error V':>8}   {'Z_total':<10} {'Error Z':>8}")
+    click.echo("─" * 76)
+    for i, (r1, r2, act_v, err_v, act_rtot, err_rtot) in enumerate(results, 1):
+        marker = " ◀" if i == 1 else ""
+        click.echo(
+            f"  {i:<3} {fmt_si(r1, 'Ω'):<12} {fmt_si(r2, 'Ω'):<12} "
+            f"{fmt_si(act_v, 'V'):<10} {err_v:>+7.2f}%   "
+            f"{fmt_si(act_rtot, 'Ω'):<10} {err_rtot:>+7.1f}%{marker}"
+        )