ee-toolkit 0.0.2__py3-none-any.whl

ee_toolkit/__about__.py

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: 2026-present Alexander Becker <nabla.becker@mailbox.org>
+#
+# SPDX-License-Identifier: MIT
+__version__ = "0.0.2"

ee_toolkit/__init__.py

@@ -0,0 +1,3 @@
+"""EE Calculator – a collection of common electrical engineering calculations."""
+
+__version__ = "0.1.0"

ee_toolkit/cli.py

@@ -0,0 +1,46 @@
+"""
+Main Click entry point for ee-calc.
+
+Commands:
+  filter      RC and LC filter cutoff frequencies
+  eseries     E-series standard value lookup
+  oscillator  LC/Colpitts/Hartley resonance frequencies
+  opamp       Op-amp gain, integrator, differentiator
+  resistor    Series / parallel resistor combinations
+"""
+import click
+from .filters    import filter_group
+from .eseries    import eseries_group
+from .oscillator import oscillator_group
+from .opamp      import opamp_group
+from .mosfet     import mosfet_group
+from .smps       import smps_group
+from .resistor   import resistor_group
+
+
+@click.group()
+@click.version_option(package_name='ee-calc')
+def cli():
+    """EE Calculator — quick electrical engineering calculations.
+
+    \b
+    Sub-commands:
+      filter      RC / LC filter cutoff frequency
+      eseries     Nearest E-series value / two-component decomposition
+      oscillator  LC, Colpitts, Hartley resonance frequency
+      opamp       Inverting / non-inverting gain, integrator, differentiator
+      mosfet      Power MOSFET calculations (gate drive, switching)
+      smps        Switching converter power-stage sizing (boost / buck)
+      resistor    Series / parallel resistor combinations
+
+    Run  ee-calc COMMAND --help  for details on a command.
+    """
+
+
+cli.add_command(filter_group,     name='filter')
+cli.add_command(eseries_group,    name='eseries')
+cli.add_command(oscillator_group, name='oscillator')
+cli.add_command(opamp_group,      name='opamp')
+cli.add_command(mosfet_group,     name='mosfet')
+cli.add_command(smps_group,       name='smps')
+cli.add_command(resistor_group,   name='resistor')

ee_toolkit/eseries.py

@@ -0,0 +1,240 @@
+"""
+E-series resistor / capacitor standard value look-up.
+
+Supported series: E12, E24, E48, E96, E192
+"""
+import math
+from typing import List, Tuple, Literal
+import click
+from .units import parse_si, fmt_si
+
+
+# ---------------------------------------------------------------------------
+# E-series base values (one decade, 3 significant figures)
+# ---------------------------------------------------------------------------
+
+_E12 = [1.0, 1.2, 1.5, 1.8, 2.2, 2.7, 3.3, 3.9, 4.7, 5.6, 6.8, 8.2]
+
+_E24 = [
+    1.0, 1.1, 1.2, 1.3, 1.5, 1.6, 1.8, 2.0, 2.2, 2.4, 2.7, 3.0,
+    3.3, 3.6, 3.9, 4.3, 4.7, 5.1, 5.6, 6.2, 6.8, 7.5, 8.2, 9.1,
+]
+
+_E48 = [
+    1.00, 1.05, 1.10, 1.15, 1.21, 1.27, 1.33, 1.40, 1.47, 1.54, 1.62, 1.69,
+    1.78, 1.87, 1.96, 2.05, 2.15, 2.26, 2.37, 2.49, 2.61, 2.74, 2.87, 3.01,
+    3.16, 3.32, 3.48, 3.65, 3.83, 4.02, 4.22, 4.42, 4.64, 4.87, 5.11, 5.36,
+    5.62, 5.90, 6.19, 6.49, 6.81, 7.15, 7.50, 7.87, 8.25, 8.66, 9.09, 9.53,
+]
+
+_E96 = [
+    1.00, 1.02, 1.05, 1.07, 1.10, 1.13, 1.15, 1.18, 1.21, 1.24, 1.27, 1.30,
+    1.33, 1.37, 1.40, 1.43, 1.47, 1.50, 1.54, 1.58, 1.62, 1.65, 1.69, 1.74,
+    1.78, 1.82, 1.87, 1.91, 1.96, 2.00, 2.05, 2.10, 2.15, 2.21, 2.26, 2.32,
+    2.37, 2.43, 2.49, 2.55, 2.61, 2.67, 2.74, 2.80, 2.87, 2.94, 3.01, 3.09,
+    3.16, 3.24, 3.32, 3.40, 3.48, 3.57, 3.65, 3.74, 3.83, 3.92, 4.02, 4.12,
+    4.22, 4.32, 4.42, 4.53, 4.64, 4.75, 4.87, 4.99, 5.11, 5.23, 5.36, 5.49,
+    5.62, 5.76, 5.90, 6.04, 6.19, 6.34, 6.49, 6.65, 6.81, 6.98, 7.15, 7.32,
+    7.50, 7.68, 7.87, 8.06, 8.25, 8.45, 8.66, 8.87, 9.09, 9.31, 9.53, 9.76,
+]
+
+# E192 computed from IEC 60063 formula: round(10^(i/192), 2 sig figs)
+def _make_e192() -> List[float]:
+    vals = []
+    for i in range(192):
+        raw = 10 ** (i / 192)
+        # round to 3 significant figures
+        mag = math.floor(math.log10(raw))
+        rounded = round(raw / 10**mag, 2) * 10**mag
+        vals.append(round(rounded, 6))
+    return vals
+
+_E192 = _make_e192()
+
+SERIES = {
+    'E12':  _E12,
+    'E24':  _E24,
+    'E48':  _E48,
+    'E96':  _E96,
+    'E192': _E192,
+}
+
+
+def all_values(series: str) -> List[float]:
+    """Return all standard values across all decades (1Ω … 10MΩ typical)."""
+    base = SERIES[series.upper()]
+    result = []
+    for exp in range(-2, 8):       # 0.01 … 10 000 000
+        for b in base:
+            result.append(round(b * (10 ** exp), 12))
+    return sorted(result)
+
+
+def _decade_candidates(target: float, base: List[float], span: int = 2) -> List[float]:
+    """Generate E-series candidate values spanning ±*span* decades around *target*.
+
+    Decade-independent: works equally for resistors (kΩ), capacitors (nF) and
+    inductors (µH), unlike the fixed-range ``all_values``.
+    """
+    decade = 10.0 ** math.floor(math.log10(target))
+    candidates = set()
+    for k in range(-span, span + 1):
+        scale = decade * (10.0 ** k)
+        for b in base:
+            candidates.add(b * scale)
+    return sorted(candidates)
+
+
+def nearest_in_series(target: float, series: str) -> Tuple[float, float]:
+    """Snap *target* to the single nearest E-series value (any decade).
+
+    Returns (value, error_pct).
+    """
+    if target <= 0:
+        raise ValueError("target must be positive")
+    base = SERIES[series.upper()]
+    snapped = min(_decade_candidates(target, base), key=lambda v: abs(v - target))
+    return snapped, (snapped - target) / target * 100.0
+
+
+def find_nearest(target: float, series: str, n: int = 3) -> List[Tuple[float, float]]:
+    """
+    Return the *n* closest standard values to *target* (value, error_pct).
+
+    Decade-independent across the full pF…GΩ range.
+    """
+    if target <= 0:
+        raise ValueError("target must be positive")
+    base = SERIES[series.upper()]
+    candidates = _decade_candidates(target, base)
+    ranked = sorted(candidates, key=lambda v: abs(v - target))[:n]
+    return [(v, (v - target) / target * 100) for v in ranked]
+
+
+def decompose(
+    target: float,
+    series: str,
+    mode: Literal['series', 'parallel'],
+    n_results: int = 5,
+) -> List[Tuple[float, float, float]]:
+    """
+    Find the best two-component (series or parallel) combination from *series*
+    that approximates *target*.
+
+    Returns list of (v1, v2, error_pct) sorted by |error|.
+    """
+    base_vals = all_values(series)
+    # Limit search space: only values within a factor of target
+    lo, hi = target * 0.001, target * 1000
+    candidates = [v for v in base_vals if lo <= v <= hi]
+
+    results = []
+    seen = set()
+
+    for v1 in candidates:
+        if mode == 'series':
+            v2_ideal = target - v1
+        else:  # parallel
+            if v1 == target:
+                continue
+            v2_ideal = (target * v1) / (v1 - target)
+
+        if v2_ideal <= 0:
+            continue
+
+        # Find nearest E-series value for v2
+        nearest = min(candidates, key=lambda v: abs(v - v2_ideal))
+        v2 = nearest
+
+        if mode == 'series':
+            actual = v1 + v2
+        else:
+            actual = (v1 * v2) / (v1 + v2)
+
+        err = (actual - target) / target * 100
+        key = (round(min(v1, v2), 12), round(max(v1, v2), 12))
+        if key not in seen:
+            seen.add(key)
+            results.append((v1, v2, err))
+
+    results.sort(key=lambda x: abs(x[2]))
+    return results[:n_results]
+
+
+# ---------------------------------------------------------------------------
+# Click commands
+# ---------------------------------------------------------------------------
+
+_SERIES_CHOICE = click.Choice(['E12', 'E24', 'E48', 'E96', 'E192'],
+                               case_sensitive=False)
+
+
+@click.group()
+def eseries_group():
+    """E-series standard value look-up (E12 … E192)."""
+
+
+@eseries_group.command('find')
+@click.option('--value', 'val_str', required=True, metavar='VALUE',
+              help='Target value, e.g. 10.5k, 220, 4.7M')
+@click.option('--series', default='E24', show_default=True,
+              type=_SERIES_CHOICE, help='E-series to search.')
+@click.option('-n', 'n', default=3, show_default=True,
+              help='Number of nearest values to show.')
+@click.option('--unit', default='Ω', show_default=True,
+              help='Unit label for display (Ω, F, H…)')
+def cmd_find(val_str, series, n, unit):
+    """Find the closest E-series standard values to a target.
+
+    \b
+    Example:
+      ee-calc eseries find --value 10.5k
+      ee-calc eseries find --value 47n --series E48 --unit F
+    """
+    target = parse_si(val_str)
+    results = find_nearest(target, series, n)
+    click.echo(f"Target : {fmt_si(target, unit)}  (series {series.upper()})")
+    click.echo(f"{'Rank':<5} {'Value':<14} {'Error':>8}")
+    click.echo("─" * 30)
+    for i, (v, err) in enumerate(results, 1):
+        marker = " ◀" if i == 1 else ""
+        click.echo(f"  {i:<3} {fmt_si(v, unit):<14} {err:>+7.3f}%{marker}")
+
+
+@eseries_group.command('decompose')
+@click.option('--value', 'val_str', required=True, metavar='VALUE',
+              help='Target value, e.g. 10.5k')
+@click.option('--series', default='E24', show_default=True,
+              type=_SERIES_CHOICE, help='E-series to use.')
+@click.option('--combo', default='series',
+              type=click.Choice(['series', 'parallel'], case_sensitive=False),
+              show_default=True, help='Combination type.')
+@click.option('-n', 'n', default=5, show_default=True,
+              help='Number of combinations to show.')
+@click.option('--unit', default='Ω', show_default=True,
+              help='Unit label for display (Ω, F, H…)')
+def cmd_decompose(val_str, series, combo, n, unit):
+    """Find two E-series values (series or parallel) that approximate a target.
+
+    \b
+    Example:
+      ee-calc eseries decompose --value 10.5k
+      ee-calc eseries decompose --value 10.5k --combo parallel
+    """
+    target = parse_si(val_str)
+    results = decompose(target, series, combo, n)
+    sym = '+' if combo == 'series' else '∥'
+    click.echo(f"Target : {fmt_si(target, unit)}  "
+               f"(series {series.upper()}, {combo} combination)")
+    click.echo(f"{'Rank':<5} {'V1':<14} {'V2':<14} {'Result':<14} {'Error':>8}")
+    click.echo("─" * 58)
+    for i, (v1, v2, err) in enumerate(results, 1):
+        if combo == 'series':
+            actual = v1 + v2
+        else:
+            actual = (v1 * v2) / (v1 + v2)
+        marker = " ◀" if i == 1 else ""
+        click.echo(
+            f"  {i:<3} {fmt_si(v1, unit):<14} {fmt_si(v2, unit):<14} "
+            f"{fmt_si(actual, unit):<14} {err:>+7.3f}%{marker}"
+        )

ee_toolkit/filters.py

@@ -0,0 +1,134 @@
+"""
+Filter cutoff / resonance frequency calculations.
+
+RC filter:    f = 1 / (2π · R · C)
+LC filter:    f = 1 / (2π · √(L · C))
+RC band-pass: two cascaded RC stages (HPF + LPF)
+"""
+import math
+from .units import parse_si, fmt_si
+
+
+def rc_cutoff(r: float, c: float) -> float:
+    """Return the -3 dB cutoff frequency of an RC filter (Hz)."""
+    return 1.0 / (2.0 * math.pi * r * c)
+
+
+def lc_resonance(l: float, c: float) -> float:
+    """Return the resonance frequency of an LC network (Hz)."""
+    return 1.0 / (2.0 * math.pi * math.sqrt(l * c))
+
+
+def rc_bandpass(r_hp: float, c_hp: float, r_lp: float, c_lp: float):
+    """Return (f_low, f_high, f_centre, bandwidth) for a two-stage RC band-pass.
+
+    The high-pass stage (R_hp, C_hp) sets the lower -3 dB edge;
+    the low-pass stage (R_lp, C_lp) sets the upper -3 dB edge.
+    """
+    f_low  = rc_cutoff(r_hp, c_hp)
+    f_high = rc_cutoff(r_lp, c_lp)
+    if f_low > f_high:
+        raise ValueError(
+            f"High-pass cutoff ({f_low:.3g} Hz) must be lower than "
+            f"low-pass cutoff ({f_high:.3g} Hz)."
+        )
+    f_centre   = math.sqrt(f_low * f_high)
+    bandwidth  = f_high - f_low
+    return f_low, f_high, f_centre, bandwidth
+
+
+# ---------------------------------------------------------------------------
+# Click commands
+# ---------------------------------------------------------------------------
+import click
+
+
+@click.group()
+def filter_group():
+    """Filter frequency calculations (RC, LC, RC band-pass)."""
+
+
+@filter_group.command('rc')
+@click.option('--r', 'r_str', required=True, metavar='VALUE',
+              help='Resistance, e.g. 10k, 4.7M, 220')
+@click.option('--c', 'c_str', required=True, metavar='VALUE',
+              help='Capacitance, e.g. 100n, 10u, 220p')
+@click.option('--type', 'ftype', default='low',
+              type=click.Choice(['low', 'high'], case_sensitive=False),
+              show_default=True, help='Filter type (informational).')
+def cmd_rc(r_str, c_str, ftype):
+    """RC filter -3 dB cutoff frequency.
+
+    \b
+    f = 1 / (2π · R · C)
+
+    Example:
+      ee-calc filter rc --r 10k --c 100n
+    """
+    r = parse_si(r_str)
+    c = parse_si(c_str)
+    f = rc_cutoff(r, c)
+    click.echo(f"RC {ftype}-pass filter")
+    click.echo(f"  R = {fmt_si(r, 'Ω')}")
+    click.echo(f"  C = {fmt_si(c, 'F')}")
+    click.echo(f"  Cutoff frequency f₋₃dB = {fmt_si(f, 'Hz')}")
+
+
+@filter_group.command('lc')
+@click.option('--l', 'l_str', required=True, metavar='VALUE',
+              help='Inductance, e.g. 10u, 1m, 470n')
+@click.option('--c', 'c_str', required=True, metavar='VALUE',
+              help='Capacitance, e.g. 100p, 10n, 1u')
+def cmd_lc(l_str, c_str):
+    """LC filter resonance frequency.
+
+    \b
+    f = 1 / (2π · √(L · C))
+
+    Example:
+      ee-calc filter lc --l 10u --c 100p
+    """
+    l = parse_si(l_str)
+    c = parse_si(c_str)
+    f = lc_resonance(l, c)
+    click.echo("LC filter / resonator")
+    click.echo(f"  L = {fmt_si(l, 'H')}")
+    click.echo(f"  C = {fmt_si(c, 'F')}")
+    click.echo(f"  Resonance frequency f₀ = {fmt_si(f, 'Hz')}")
+
+@filter_group.command('bp')
+@click.option('--r1', 'r1_str', required=True, metavar='VALUE',
+              help='High-pass resistance, e.g. 10k')
+@click.option('--c1', 'c1_str', required=True, metavar='VALUE',
+              help='High-pass capacitance, e.g. 100n')
+@click.option('--r2', 'r2_str', required=True, metavar='VALUE',
+              help='Low-pass resistance, e.g. 10k')
+@click.option('--c2', 'c2_str', required=True, metavar='VALUE',
+              help='Low-pass capacitance, e.g. 10n')
+def cmd_bp(r1_str, c1_str, r2_str, c2_str):
+    """RC band-pass filter (cascaded high-pass + low-pass stages).
+
+    \b
+    f_low  = 1 / (2π · R1 · C1)   ← high-pass edge
+    f_high = 1 / (2π · R2 · C2)   ← low-pass edge
+    f₀     = √(f_low · f_high)    ← geometric centre
+    BW     = f_high − f_low
+
+    Example:
+      ee-calc filter bp --r1 10k --c1 100n --r2 10k --c2 10n
+    """
+    r1 = parse_si(r1_str)
+    c1 = parse_si(c1_str)
+    r2 = parse_si(r2_str)
+    c2 = parse_si(c2_str)
+    try:
+        f_low, f_high, f_centre, bw = rc_bandpass(r1, c1, r2, c2)
+    except ValueError as exc:
+        raise click.UsageError(str(exc)) from exc
+    click.echo("RC band-pass filter")
+    click.echo(f"  High-pass stage  R1 = {fmt_si(r1, 'Ω')},  C1 = {fmt_si(c1, 'F')}")
+    click.echo(f"  Low-pass  stage  R2 = {fmt_si(r2, 'Ω')},  C2 = {fmt_si(c2, 'F')}")
+    click.echo(f"  Lower edge  f_low  = {fmt_si(f_low,    'Hz')}")
+    click.echo(f"  Upper edge  f_high = {fmt_si(f_high,   'Hz')}")
+    click.echo(f"  Centre freq f₀     = {fmt_si(f_centre, 'Hz')}")
+    click.echo(f"  Bandwidth   BW     = {fmt_si(bw,       'Hz')}")

ee_toolkit/mosfet.py

@@ -0,0 +1,95 @@
+"""
+Power MOSFET calculations.
+
+Gate Drive Requirements
+-----------------------
+  Required Drive Current: Ig = Qg / t_sw
+  Switching Time:         t_sw = Qg / Ig
+  Gate Drive Power:       Pgate = Qg * Vdr * f_sw
+  Peak Current:           Ig_peak = Vdr / Rg_total
+"""
+import click
+from .units import parse_si, fmt_si
+
+
+def ig_from_tsw(qg: float, tsw: float) -> float:
+    """Average gate current required for a specific switching time."""
+    return qg / tsw
+
+
+def tsw_from_ig(qg: float, ig: float) -> float:
+    """Estimated switching time for a given average gate current."""
+    return qg / ig
+
+
+def pgate_power(qg: float, vdr: float, fsw: float) -> float:
+    """Power dissipated in the gate driver."""
+    return qg * vdr * fsw
+
+
+def ig_peak_from_rg(vdr: float, rg: float) -> float:
+    """Peak gate drive current limited by total gate resistance."""
+    return vdr / rg
+
+
+@click.group()
+def mosfet_group():
+    """Power MOSFET calculations (gate drive, switching)."""
+
+
+@mosfet_group.command('gate')
+@click.option('--qg', 'qg_str', required=True, metavar='VALUE',
+              help='Total gate charge (Qg), e.g. 50n')
+@click.option('--vdr', 'vdr_str', required=True, metavar='VALUE',
+              help='Gate drive voltage (Vdr), e.g. 12')
+@click.option('--tsw', 'tsw_str', default=None, metavar='VALUE',
+              help='Desired switching time (t_sw), e.g. 20n')
+@click.option('--ig', 'ig_str', default=None, metavar='VALUE',
+              help='Available gate drive current (Ig), e.g. 1.5')
+@click.option('--rg', 'rg_str', default=None, metavar='VALUE',
+              help='Total gate resistance (driver + ext + int), e.g. 10')
+@click.option('--fsw', 'fsw_str', default=None, metavar='VALUE',
+              help='Switching frequency, e.g. 100k')
+def cmd_gate(qg_str, vdr_str, tsw_str, ig_str, rg_str, fsw_str):
+    """Gate driver requirements for power MOSFETs.
+
+    \b
+    Formulas:
+      Ig_req  = Qg / t_sw
+      t_sw    = Qg / Ig
+      P_gate  = Qg * Vdr * f_sw
+      Ig_peak = Vdr / Rg_total
+
+    Example:
+      ee-calc mosfet gate --qg 50n --vdr 12 --tsw 20n --fsw 100k
+    """
+    qg = parse_si(qg_str)
+    vdr = parse_si(vdr_str)
+
+    click.echo("Power MOSFET Gate Drive")
+    click.echo(f"  Qg  = {fmt_si(qg, 'C')}")
+    click.echo(f"  Vdr = {fmt_si(vdr, 'V')}")
+
+    if tsw_str:
+        tsw = parse_si(tsw_str)
+        ig_req = ig_from_tsw(qg, tsw)
+        click.echo(f"\nTarget Switching Time: t_sw = {fmt_si(tsw, 's')}")
+        click.echo(f"  Required average gate current (Ig) = {fmt_si(ig_req, 'A')}")
+
+    if ig_str:
+        ig = parse_si(ig_str)
+        tsw_est = tsw_from_ig(qg, ig)
+        click.echo(f"\nAvailable Gate Current: Ig = {fmt_si(ig, 'A')}")
+        click.echo(f"  Estimated switching time (t_sw) = {fmt_si(tsw_est, 's')}")
+
+    if rg_str:
+        rg = parse_si(rg_str)
+        ig_peak = ig_peak_from_rg(vdr, rg)
+        click.echo(f"\nTotal Gate Resistance: Rg = {fmt_si(rg, 'Ω')}")
+        click.echo(f"  Peak driver current (Ipk) = {fmt_si(ig_peak, 'A')}")
+
+    if fsw_str:
+        fsw = parse_si(fsw_str)
+        pd = pgate_power(qg, vdr, fsw)
+        click.echo(f"\nSwitching Frequency: f_sw = {fmt_si(fsw, 'Hz')}")
+        click.echo(f"  Gate driver power (Pd) = {fmt_si(pd, 'W')}")