ee-toolkit 0.0.2__tar.gz → 0.1.0__tar.gz

{ee_toolkit-0.0.2 → ee_toolkit-0.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ee-toolkit
-Version: 0.0.2
+Version: 0.1.0
 Project-URL: Documentation, https://git.sr.ht/~laplace/ee-toolkit#readme
 Project-URL: Issues, https://git.sr.ht/~laplace/ee-toolkit/todo
 Project-URL: Source, https://git.sr.ht/~laplace/ee-toolkit

{ee_toolkit-0.0.2 → ee_toolkit-0.1.0}/src/ee_toolkit/__about__.py

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

{ee_toolkit-0.0.2 → ee_toolkit-0.1.0}/src/ee_toolkit/cli.py

@@ -6,12 +6,15 @@ Commands:
   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 .resistor   import resistor_group
 
 
 @click.group()
@@ -25,6 +28,8 @@ def cli():
       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)
+      resistor    Series / parallel resistor combinations
 
     Run  ee-calc COMMAND --help  for details on a command.
     """
@@ -34,3 +39,5 @@ 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(resistor_group,   name='resistor')

ee_toolkit-0.1.0/src/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')}")

ee_toolkit-0.1.0/src/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}"
+        )