stimgrid 0.2.0__py3-none-any.whl

stimgrid/__init__.py

@@ -0,0 +1,17 @@
+"""stimgrid: fit stimulation pulses to what a stimulator can actually produce.
+
+Rounds a planned pulse to a device's amplitude and timing steps, reports what is
+really delivered, and finds the nearest exactly charge-balanced pulse.
+For research use; check results on your own hardware.
+"""
+
+from .devices import PRESETS, Device, cortical_labs_cl, intan_rhs2116, mcs_stg4000, mcs_stg5, preset, tdt_iz2
+from .fit import Delivered, FitReport, Issue, Pulse, RateFit, Rates, fit
+from .loader import InputError, from_dict, load
+
+__version__ = "0.2.0"
+__all__ = [
+    "PRESETS", "Delivered", "Device", "FitReport", "InputError", "Issue", "Pulse", "RateFit", "Rates",
+    "cortical_labs_cl", "fit", "from_dict", "intan_rhs2116", "load", "mcs_stg4000", "mcs_stg5", "preset",
+    "tdt_iz2", "__version__",
+]

stimgrid/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

stimgrid/cli.py

@@ -0,0 +1,177 @@
+"""Command line.
+
+  stimgrid fit FILE|-     fit the pulse in a request file (or stdin)
+  stimgrid quick ...      fit a pulse given as flags
+  stimgrid devices        list the built-in device presets
+
+Exit codes: 0 fitted with no errors (and no warnings with --strict), 1 errors
+(or warnings with --strict), 2 bad input or usage, 3 internal error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import inspect
+import json
+import sys
+from typing import List, Optional
+
+from . import __version__
+from .devices import PRESETS, Device, override, preset
+from .fit import Delivered, FitReport, Pulse, Rates, fit
+from .loader import InputError, load
+
+EXIT_OK, EXIT_ISSUES, EXIT_INPUT, EXIT_INTERNAL = 0, 1, 2, 3
+NOTE = "Values are what the device grid allows; check them on your own hardware. Research use only."
+
+
+def _f(x: Optional[float], digits: int = 6) -> str:
+    return "-" if x is None else f"{x:.{digits}g}"
+
+
+def _row(label: str, d: Delivered) -> str:
+    second = f"{_f(d.second_amplitude_ua)} µA x {_f(d.second_width_us)} µs" if d.biphasic else "(monophasic)"
+    return (f"  {label:<9} {_f(d.amplitude_ua)} µA x {_f(d.width_us)} µs | gap {_f(d.gap_us)} µs | {second}\n"
+            f"  {'':<9} charge {_f(d.first_charge_nc, 5)} nC ({d.charge_change:+.2%} vs plan), "
+            f"net {_f(d.net_charge_nc, 4)} nC, imbalance {d.imbalance:.4%}")
+
+
+def render(report: FitReport) -> str:
+    t = report.target
+    second = (f"{_f(t['second_amplitude_ua'] or t['amplitude_ua'])} µA x {_f(t['second_width_us'] or t['width_us'])} µs"
+              if t["biphasic"] else "(monophasic)")
+    dev = report.device
+    amp = "continuous" if dev["amplitude_step_ua"] is None else f"{_f(dev['amplitude_step_ua'])} µA steps"
+    lines = [
+        f"device: {dev['name']}: {_f(dev['time_step_us'])} µs time steps, {amp}"
+        + (f", max {_f(dev['max_amplitude_ua'])} µA" if dev["max_amplitude_ua"] else ""),
+        f"  plan      {_f(t['amplitude_ua'])} µA x {_f(t['width_us'])} µs | gap {_f(t['gap_us'])} µs | {second}",
+        _row("rounded", report.rounded),
+    ]
+    if report.balanced is not None:
+        lines.append(_row("balanced", report.balanced))
+        for i, alt in enumerate(report.alternatives, 1):
+            lines.append(_row(f"option {i}", alt))
+    for r in report.rates:
+        lines.append(f"  rate      {r.name} {_f(r.target_hz)} Hz -> {_f(r.delivered_hz)} Hz "
+                     f"({r.period_ticks} steps per period, {r.change:+.3%})")
+    lines.append("")
+    for i in report.issues:
+        lines.append(f"{i.severity.upper():<7} {i.code} {i.message}")
+    if report.issues:
+        lines.append("")
+    lines.append(f"best pulse: {json.dumps(report.best.as_pulse())}")
+    lines.append(f"result: {'OK' if report.ok else 'ERROR'}")
+    lines.append(NOTE)
+    return "\n".join(lines)
+
+
+def _emit(report: FitReport, fmt: str, strict: bool) -> int:
+    if fmt == "json":
+        data = report.to_dict()
+        data.update({"tool": "stimgrid", "tool_version": __version__, "note": NOTE})
+        print(json.dumps(data, indent=2, ensure_ascii=False, allow_nan=False))
+    elif fmt == "pulse":
+        print(json.dumps(report.best.as_pulse()))
+    else:
+        print(render(report))
+    failed = (not report.ok) or (strict and bool(report.issues))
+    return EXIT_ISSUES if failed else EXIT_OK
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="stimgrid", description="Fit stimulation pulses to what a stimulator can "
+                                     "actually produce, and find the nearest exactly charge-balanced pulse.")
+    parser.add_argument("--version", action="version", version=f"stimgrid {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    def output(p: argparse.ArgumentParser) -> None:
+        p.add_argument("--format", choices=("text", "json", "pulse"), default="text",
+                       help="pulse prints only the best pulse as JSON")
+        p.add_argument("--strict", action="store_true", help="treat warnings as failures (exit code 1)")
+
+    p_fit = sub.add_parser("fit", help="fit the pulse in a request file ('-' reads stdin)")
+    p_fit.add_argument("file")
+    output(p_fit)
+
+    q = sub.add_parser("quick", help="fit a pulse given as flags")
+    q.add_argument("--device", choices=sorted(PRESETS), help="start from a preset")
+    q.add_argument("--step-ua", type=float, help="intan-rhs2116: current step size")
+    q.add_argument("--sample-rate-hz", type=float, help="intan-rhs2116, tdt-iz2: sampling rate")
+    q.add_argument("--range-ua", type=float, help="mcs-stg4000, mcs-stg5, tdt-iz2: current range (max µA)")
+    q.add_argument("--time-step-us", type=float)
+    q.add_argument("--amplitude-step-ua", type=float)
+    q.add_argument("--max-amplitude-ua", type=float)
+    q.add_argument("--max-charge-per-phase-nc", type=float)
+    q.add_argument("--amplitude-ua", type=float, required=True)
+    q.add_argument("--width-us", type=float, required=True)
+    q.add_argument("--second-amplitude-ua", type=float)
+    q.add_argument("--second-width-us", type=float)
+    q.add_argument("--gap-us", type=float, default=0.0)
+    q.add_argument("--monophasic", action="store_true")
+    q.add_argument("--frequency-hz", type=float)
+    q.add_argument("--intra-burst-hz", type=float)
+    q.add_argument("--burst-rate-hz", type=float)
+    q.add_argument("--max-imbalance", type=float, default=0.0)
+    q.add_argument("--keep-first", action="store_true", help="balance with the second phase only")
+    output(q)
+
+    sub.add_parser("devices", help="list the built-in device presets")
+    return parser
+
+
+def _quick_device(args: argparse.Namespace) -> Device:
+    changes = dict(time_step_us=args.time_step_us, amplitude_step_ua=args.amplitude_step_ua,
+                   max_amplitude_ua=args.max_amplitude_ua, max_charge_per_phase_nc=args.max_charge_per_phase_nc)
+    if args.device:
+        given = (("step_ua", args.step_ua), ("sample_rate_hz", args.sample_rate_hz), ("range_ua", args.range_ua))
+        options = {k: v for k, v in given if v is not None}
+        accepted = inspect.signature(PRESETS[args.device]).parameters
+        wrong = [k for k in options if k not in accepted]
+        if wrong:
+            flags = ", ".join("--" + k.replace("_", "-") for k in wrong)
+            raise ValueError(f"{flags} does not apply to {args.device}")
+        return override(preset(args.device, **options), **changes)
+    if args.time_step_us is None:
+        raise ValueError("give --device or at least --time-step-us")
+    return Device(name="command line", **{k: v for k, v in changes.items() if v is not None})
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    args = _parser().parse_args(argv)  # usage errors exit with 2
+    try:
+        if args.command == "devices":
+            for name in sorted(PRESETS):
+                d = preset(name)
+                amp = "continuous amplitude" if d.continuous_amplitude else f"{d.amplitude_step_ua:g} µA steps"
+                print(f"{name}: {d.time_step_us:.6g} µs time steps, {amp}\n  source: {d.source}")
+                if d.note:
+                    print(f"  note: {d.note}")
+            return EXIT_OK
+        if args.command == "fit":
+            pulse, device, rates, options = load(args.file)
+        else:
+            try:
+                device = _quick_device(args)
+                pulse = Pulse(args.amplitude_ua, args.width_us, biphasic=not args.monophasic,
+                              second_amplitude_ua=args.second_amplitude_ua, second_width_us=args.second_width_us,
+                              gap_us=args.gap_us)
+                rates = Rates(args.frequency_hz, args.intra_burst_hz, args.burst_rate_hz)
+            except ValueError as exc:
+                raise InputError(str(exc)) from None
+            options = {"max_imbalance": args.max_imbalance, "keep_first": args.keep_first}
+        try:
+            report = fit(pulse, device, rates, **options)
+        except ValueError as exc:
+            raise InputError(str(exc)) from None
+        return _emit(report, args.format, args.strict)
+    except (InputError, OSError) as exc:
+        print(f"stimgrid: {exc}", file=sys.stderr)
+        return EXIT_INPUT
+    except Exception as exc:  # noqa: BLE001 - report, don't crash with a traceback
+        print(f"stimgrid: internal error: {exc!r}", file=sys.stderr)
+        return EXIT_INTERNAL
+
+
+if __name__ == "__main__":
+    sys.exit(main())

stimgrid/devices.py

@@ -0,0 +1,227 @@
+"""Stimulator resolution: the amplitudes and timings a device can actually produce.
+
+A device has a timing grid (every phase width, gap and period is a whole number
+of time steps) and an amplitude grid (every current is a whole number of
+amplitude steps), plus optional ranges. Amplitude can also be continuous when a
+device does not publish its step.
+
+Built-in presets use only figures from the vendor's own documentation, cited in
+`source`. Check them against your device and its settings before relying on them.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, replace
+from typing import Callable, Dict, Optional
+
+INTAN_RHS2116_STEPS_UA = (0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1.0, 2.0, 5.0, 10.0)
+INTAN_SOURCE = ("Intan Technologies RHS2116 datasheet: global current step sizes 10 nA to 10 µA, "
+                "8-bit magnitude; pulse timing set by the host's command timing")
+CL_SOURCE = ("Cortical Labs CL API docs (docs.corticallabs.com/cl.html), StimDesign: phase width evenly "
+             "divisible by 20 µs, |current| at most 3.0 µA, charge at most 3.0 nC")
+MCS_STG4000_RANGES = {1600.0: 0.2, 16000.0: 2.0}  # max µA per channel: current step µA
+MCS_STG4000_SOURCE = ("Multi Channel Systems STG 4002/4004/4008 datasheets (1.6 mA and 16 mA versions, 2021): "
+                      "output current resolution 200 nA (1.6 mA) or 2000 nA (16 mA), time resolution 20 µs, "
+                      "maximum frequency 25 kHz")
+MCS_STG5_RANGES = {160.0: 0.1, 1600.0: 1.0, 16000.0: 10.0}
+MCS_STG5_SOURCE = ("Multi Channel Systems STG5 brochure (2024): up to 160 µA (resolution 100 nA), 1.6 mA (1 µA) "
+                   "or 16 mA (10 µA); temporal pulse resolution 5 µs, up to 100 kHz")
+TDT_IZ2_RANGES = {300.0: "IZ2 / IZ2M", 3000.0: "IZ2H / IZ2MH"}
+TDT_IZ2_MAX_RATE_HZ = 195312.5
+TDT_IZ2_SOURCE = ("Tucker-Davis Technologies IZ2 manual and IZ2M/IZ2MH spec sheet: output ±300 µA (IZ2, IZ2M) "
+                  "or ±3 mA (IZ2H, IZ2MH); the stimulator runs at the sampling rate of its RZ processor, "
+                  "pulses as short as one sample")
+
+
+@dataclass(frozen=True)
+class Device:
+    name: str
+    time_step_us: float
+    amplitude_step_ua: Optional[float] = None  # None: amplitude is continuous
+    max_amplitude_ua: Optional[float] = None
+    min_phase_us: Optional[float] = None  # defaults to one time step
+    max_phase_us: Optional[float] = None
+    max_charge_per_phase_nc: Optional[float] = None
+    max_frequency_hz: Optional[float] = None
+    source: str = "user-supplied"
+    note: str = ""
+
+    def __post_init__(self) -> None:
+        if not (isinstance(self.name, str) and self.name):
+            raise ValueError("name must be a non-empty string")
+        _positive("time_step_us", self.time_step_us)
+        for field_name in ("amplitude_step_ua", "max_amplitude_ua", "min_phase_us", "max_phase_us",
+                           "max_charge_per_phase_nc", "max_frequency_hz"):
+            value = getattr(self, field_name)
+            if value is not None:
+                _positive(field_name, value)
+        if (self.amplitude_step_ua is not None and self.max_amplitude_ua is not None
+                and self.max_amplitude_ua < self.amplitude_step_ua):
+            raise ValueError("max_amplitude_ua is smaller than one amplitude step")
+        if self.min_phase_us is not None and self.max_phase_us is not None and self.max_phase_us < self.min_phase_us:
+            raise ValueError("max_phase_us is smaller than min_phase_us")
+
+    # --- grid helpers ---------------------------------------------------------------------------------------
+
+    @property
+    def continuous_amplitude(self) -> bool:
+        return self.amplitude_step_ua is None
+
+    @property
+    def min_ticks(self) -> int:
+        if self.min_phase_us is None:
+            return 1
+        return max(1, math.ceil(self.min_phase_us / self.time_step_us - 1e-9))
+
+    @property
+    def max_ticks(self) -> Optional[int]:
+        if self.max_phase_us is None:
+            return None
+        return math.floor(self.max_phase_us / self.time_step_us + 1e-9)
+
+    @property
+    def max_amplitude_steps(self) -> Optional[int]:
+        if self.continuous_amplitude or self.max_amplitude_ua is None:
+            return None
+        return math.floor(self.max_amplitude_ua / self.amplitude_step_ua + 1e-9)
+
+    def ticks(self, duration_us: float) -> int:
+        return _round_half_up(duration_us / self.time_step_us)
+
+    def us(self, ticks: int) -> float:
+        return ticks * self.time_step_us
+
+    def amp_steps(self, amplitude_ua: float) -> int:
+        return _round_half_up(amplitude_ua / self.amplitude_step_ua)
+
+    def ua(self, steps: int) -> float:
+        return steps * self.amplitude_step_ua
+
+
+# --- presets ----------------------------------------------------------------------------------------------------
+
+def intan_rhs2116(step_ua: float = 1.0, sample_rate_hz: float = 30000.0) -> Device:
+    """Intan RHS2116 with one global current step and a host timing grid of one sample.
+
+    The chip has no pulse timers: the host sets every edge, normally once per sample,
+    so the timing grid is 1 / sample rate. Full scale is 255 steps.
+    """
+    if not any(math.isclose(step_ua, s, rel_tol=1e-9) for s in INTAN_RHS2116_STEPS_UA):
+        allowed = ", ".join(f"{s:g}" for s in INTAN_RHS2116_STEPS_UA)
+        raise ValueError(f"the RHS2116 step size must be one of {allowed} µA")
+    _positive("sample_rate_hz", sample_rate_hz)
+    return Device(
+        name=f"intan-rhs2116 (step {step_ua:g} µA, {sample_rate_hz:g} samples/s)",
+        time_step_us=1e6 / sample_rate_hz,
+        amplitude_step_ua=step_ua,
+        max_amplitude_ua=255 * step_ua,
+        source=INTAN_SOURCE,
+        note="Timing grid assumes edges on sample boundaries; check your host software.",
+    )
+
+
+def cortical_labs_cl() -> Device:
+    return Device(
+        name="cortical-labs-cl",
+        time_step_us=20.0,
+        amplitude_step_ua=None,
+        max_amplitude_ua=3.0,
+        max_charge_per_phase_nc=3.0,
+        source=CL_SOURCE,
+        note="The docs give no amplitude step, so amplitude is treated as continuous. They also limit "
+             "burst_hz to 200 Hz for bursts.",
+    )
+
+
+def mcs_stg4000(range_ua: float = 1600.0) -> Device:
+    """MCS STG 4002/4004/4008 in current mode. The range is fixed by the model version you bought."""
+    step = _pick_range("the STG4000 version", range_ua, MCS_STG4000_RANGES)
+    return Device(
+        name=f"mcs-stg4000 ({range_ua / 1000:g} mA version)",
+        time_step_us=20.0,
+        amplitude_step_ua=step,
+        max_amplitude_ua=range_ua,
+        max_frequency_hz=25000.0,
+        source=MCS_STG4000_SOURCE,
+        note="Current mode. The 160 µA version is not included: its official datasheet could not be confirmed.",
+    )
+
+
+def mcs_stg5(range_ua: float = 1600.0) -> Device:
+    """MCS STG5 in current mode, in one of its three ranges."""
+    step = _pick_range("the STG5 range", range_ua, MCS_STG5_RANGES)
+    return Device(
+        name=f"mcs-stg5 (up to {range_ua:g} µA)",
+        time_step_us=5.0,
+        amplitude_step_ua=step,
+        max_amplitude_ua=range_ua,
+        max_frequency_hz=100000.0,
+        source=MCS_STG5_SOURCE,
+        note="Current mode. Figures are from the product brochure.",
+    )
+
+
+def tdt_iz2(range_ua: float = 300.0, sample_rate_hz: float = 24414.0625) -> Device:
+    """TDT IZ2-family stimulator; the timing grid is one sample of the RZ processor driving it."""
+    model = TDT_IZ2_RANGES.get(float(range_ua)) if _is_number(range_ua) else None
+    if model is None:
+        raise ValueError("range_ua must be 300 (IZ2, IZ2M) or 3000 (IZ2H, IZ2MH)")
+    _positive("sample_rate_hz", sample_rate_hz)
+    if sample_rate_hz > TDT_IZ2_MAX_RATE_HZ:
+        raise ValueError(f"sample_rate_hz is above the IZ2 family's maximum of {TDT_IZ2_MAX_RATE_HZ:g}")
+    return Device(
+        name=f"tdt-iz2 ({model}, {sample_rate_hz:g} samples/s)",
+        time_step_us=1e6 / sample_rate_hz,
+        amplitude_step_ua=None,
+        max_amplitude_ua=float(range_ua),
+        source=TDT_IZ2_SOURCE,
+        note="TDT publishes no current step, so amplitude is treated as continuous. Use your RZ's real "
+             "sampling rate (for example 24414.0625, 48828.125, 97656.25 or 195312.5); the larger IZ2 "
+             "models support only the lower rates.",
+    )
+
+
+PRESETS: Dict[str, Callable[..., Device]] = {
+    "intan-rhs2116": intan_rhs2116,
+    "cortical-labs-cl": cortical_labs_cl,
+    "mcs-stg4000": mcs_stg4000,
+    "mcs-stg5": mcs_stg5,
+    "tdt-iz2": tdt_iz2,
+}
+
+
+def preset(name: str, **options: float) -> Device:
+    try:
+        make = PRESETS[name]
+    except KeyError:
+        raise ValueError(f"unknown device preset {name!r}; known: {', '.join(sorted(PRESETS))}") from None
+    return make(**options)
+
+
+def override(device: Device, **fields) -> Device:
+    """A copy of a device with some fields changed (None values are ignored)."""
+    changes = {k: v for k, v in fields.items() if v is not None}
+    return replace(device, **changes) if changes else device
+
+
+def _round_half_up(x: float) -> int:
+    """Round to the nearest whole number, halves up (Python's round() sends 4.5 to 4)."""
+    return int(math.floor(x + 0.5 + 1e-9))
+
+
+def _is_number(value: object) -> bool:
+    return isinstance(value, (int, float)) and not isinstance(value, bool) and math.isfinite(value)
+
+
+def _pick_range(what: str, range_ua: object, ranges: Dict[float, float]) -> float:
+    for top, step in ranges.items():
+        if _is_number(range_ua) and math.isclose(range_ua, top, rel_tol=1e-9):
+            return step
+    raise ValueError(f"range_ua for {what} must be one of {', '.join(f'{r:g}' for r in ranges)} µA")
+
+
+def _positive(name: str, value: object) -> None:
+    if not (isinstance(value, (int, float)) and not isinstance(value, bool) and math.isfinite(value)
+            and value > 0):
+        raise ValueError(f"{name} must be a positive number")

stimgrid/fit.py

@@ -0,0 +1,421 @@
+"""Fit a planned pulse to a device's grid.
+
+Two answers come back:
+
+- rounded: what the device delivers if each value is simply rounded to its grid.
+  An asymmetric pulse that was charge-balanced on paper often is not after this.
+- balanced: the nearest pulse on the grid whose two phases carry equal charge,
+  found by searching small changes to both phases (mostly the second phase's
+  width and amplitude, the usual balancing knobs).
+
+On a gridded device charge balance is checked exactly, in whole amplitude steps
+times whole time steps, so "balanced" means equal to the last bit, not "close".
+Pulse rates are also rounded to whole periods and the delivered rate reported.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import asdict, dataclass, field
+from typing import Iterable, List, Optional, Tuple
+
+from .devices import Device, _positive, _round_half_up
+
+MAX_SECOND_WIDTH_CANDIDATES = 4001
+_EPS = 1e-9
+
+
+@dataclass(frozen=True)
+class Pulse:
+    """The pulse you planned. Units: µA and µs."""
+
+    amplitude_ua: float
+    width_us: float
+    biphasic: bool = True
+    second_amplitude_ua: Optional[float] = None  # defaults to amplitude_ua
+    second_width_us: Optional[float] = None  # defaults to width_us
+    gap_us: float = 0.0
+
+    def __post_init__(self) -> None:
+        _positive("amplitude_ua", self.amplitude_ua)
+        _positive("width_us", self.width_us)
+        if not (isinstance(self.gap_us, (int, float)) and not isinstance(self.gap_us, bool)
+                and math.isfinite(self.gap_us) and self.gap_us >= 0):
+            raise ValueError("gap_us must be zero or a positive number")
+        if self.second_amplitude_ua is not None:
+            _positive("second_amplitude_ua", self.second_amplitude_ua)
+        if self.second_width_us is not None:
+            _positive("second_width_us", self.second_width_us)
+        if not isinstance(self.biphasic, bool):
+            raise ValueError("biphasic must be true or false")
+
+    @property
+    def a2(self) -> float:
+        return self.amplitude_ua if self.second_amplitude_ua is None else self.second_amplitude_ua
+
+    @property
+    def w2(self) -> float:
+        return self.width_us if self.second_width_us is None else self.second_width_us
+
+
+@dataclass(frozen=True)
+class Rates:
+    """Pulse rates to round to whole periods. All optional."""
+
+    frequency_hz: Optional[float] = None  # uniform train
+    intra_burst_hz: Optional[float] = None  # pulses inside a burst
+    burst_rate_hz: Optional[float] = None  # bursts per second
+
+    def __post_init__(self) -> None:
+        for name in ("frequency_hz", "intra_burst_hz", "burst_rate_hz"):
+            if getattr(self, name) is not None:
+                _positive(name, getattr(self, name))
+
+    def items(self) -> Iterable[Tuple[str, float]]:
+        for name in ("frequency_hz", "intra_burst_hz", "burst_rate_hz"):
+            value = getattr(self, name)
+            if value is not None:
+                yield name, value
+
+
+@dataclass
+class Delivered:
+    """A pulse exactly as the device can produce it."""
+
+    amplitude_ua: float
+    width_us: float
+    biphasic: bool
+    second_amplitude_ua: Optional[float]
+    second_width_us: Optional[float]
+    gap_us: float
+    width_ticks: int
+    second_width_ticks: Optional[int]
+    gap_ticks: int
+    amplitude_steps: Optional[int]  # None when amplitude is continuous
+    second_amplitude_steps: Optional[int]
+    first_charge_nc: float
+    second_charge_nc: float
+    net_charge_nc: float
+    imbalance: float  # |Q1 - Q2| / max(Q1, Q2); 0 is exactly balanced
+    duration_us: float
+    duration_ticks: int
+    charge_change: float  # first-phase charge versus the planned pulse, as a fraction
+
+    def as_pulse(self) -> dict:
+        """The pulse in the common JSON shape (amplitude_ua, width_us, ...)."""
+        out = {"amplitude_ua": _clean(self.amplitude_ua), "width_us": _clean(self.width_us)}
+        if not self.biphasic:
+            out["biphasic"] = False
+        else:
+            out["second_amplitude_ua"] = _clean(self.second_amplitude_ua)
+            out["second_width_us"] = _clean(self.second_width_us)
+        if self.gap_ticks:
+            out["gap_us"] = _clean(self.gap_us)
+        return out
+
+
+@dataclass
+class RateFit:
+    name: str
+    target_hz: float
+    period_ticks: int
+    delivered_hz: float
+    change: float  # delivered versus target, as a fraction
+
+
+@dataclass
+class Issue:
+    code: str
+    severity: str  # "error" or "warning"
+    message: str
+
+
+@dataclass
+class FitReport:
+    device: dict
+    target: dict
+    rounded: Delivered
+    balanced: Optional[Delivered]  # None for monophasic pulses
+    alternatives: List[Delivered]
+    rates: List[RateFit]
+    issues: List[Issue]
+    max_imbalance: float
+
+    @property
+    def ok(self) -> bool:
+        return not any(i.severity == "error" for i in self.issues)
+
+    @property
+    def best(self) -> Delivered:
+        return self.balanced or self.rounded
+
+    def to_dict(self) -> dict:
+        data = asdict(self)
+        data["ok"] = self.ok
+        data["best_pulse"] = self.best.as_pulse()
+        return data
+
+
+def fit(pulse: Pulse, device: Device, rates: Optional[Rates] = None, max_imbalance: float = 0.0,
+        keep_first: bool = False, search_steps: int = 2) -> FitReport:
+    """Round a pulse to a device's grid, and find the nearest exactly balanced version.
+
+    max_imbalance: the imbalance accepted as balanced (0 means exact).
+    keep_first: keep the first phase as rounded and balance with the second phase only.
+    search_steps: how many grid steps the first phase may move either way while searching.
+    """
+    if not (isinstance(max_imbalance, (int, float)) and 0 <= max_imbalance < 1):
+        raise ValueError("max_imbalance must be at least 0 and below 1")
+    if not (isinstance(search_steps, int) and 0 <= search_steps <= 20):
+        raise ValueError("search_steps must be a whole number from 0 to 20")
+    rates = rates or Rates()
+    issues: List[Issue] = []
+
+    a1, a1_issue = _grid_amplitude(pulse.amplitude_ua, device, "amplitude_ua")
+    w1, w1_issue = _grid_width(pulse.width_us, device, "width_us")
+    gap = device.ticks(pulse.gap_us)
+    issues += [i for i in (a1_issue, w1_issue) if i]
+    if pulse.biphasic:
+        a2, a2_issue = _grid_amplitude(pulse.a2, device, "second_amplitude_ua")
+        w2, w2_issue = _grid_width(pulse.w2, device, "second_width_us")
+        issues += [i for i in (a2_issue, w2_issue) if i]
+    else:
+        a2 = w2 = None
+    rounded = _deliver(pulse, device, a1, w1, a2, w2, gap)
+    if pulse.gap_us and gap == 0:
+        issues.append(Issue("SG105", "warning", f"gap_us {pulse.gap_us:g} rounds to 0 on a "
+                                                f"{device.time_step_us:.6g} µs grid"))
+    for name, want, got in _moved(pulse, rounded):
+        issues.append(Issue("SG106", "warning", f"{name} {want:g} becomes {got:.6g} after rounding "
+                                                f"({(got - want) / want:+.1%})"))
+
+    balanced, alternatives = None, []
+    if pulse.biphasic:
+        if rounded.imbalance > max_imbalance + _EPS:
+            issues.append(Issue("SG201", "warning",
+                                f"simple rounding leaves the pulse unbalanced (imbalance {rounded.imbalance:.4%}, "
+                                f"net {rounded.net_charge_nc:.4g} nC per pulse)"))
+        ranked = _search(pulse, device, a1, w1, w2, gap, max_imbalance, keep_first, search_steps)
+        if ranked:
+            balanced, alternatives = ranked[0], ranked[1:4]
+            if balanced.imbalance > max_imbalance + _EPS:
+                issues.append(Issue("SG202", "error",
+                                    f"no pulse within the search is balanced to {max_imbalance:.4%}; the best "
+                                    f"found has imbalance {balanced.imbalance:.4%}"))
+            if abs(balanced.charge_change) > 0.05:
+                issues.append(Issue("SG203", "warning",
+                                    f"the balanced pulse changes charge per phase by {balanced.charge_change:+.1%}"))
+        else:
+            issues.append(Issue("SG202", "error", "no pulse on the device grid fits the search range and limits"))
+
+    best = balanced or rounded
+    if device.max_charge_per_phase_nc is not None:
+        q = max(best.first_charge_nc, best.second_charge_nc)
+        if q > device.max_charge_per_phase_nc + _EPS:
+            issues.append(Issue("SG104", "error", f"charge per phase {q:.4g} nC is above the device's "
+                                                  f"{device.max_charge_per_phase_nc:g} nC"))
+    rate_fits = _rates(rates, device, best, issues)
+    issues.sort(key=lambda i: (i.severity != "error", i.code))
+    return FitReport(asdict(device), asdict(pulse), rounded, balanced, alternatives, rate_fits, issues,
+                     max_imbalance)
+
+
+# --- grid rounding -----------------------------------------------------------------------------------------------
+
+def _grid_amplitude(value: float, device: Device, name: str) -> Tuple[float, Optional[Issue]]:
+    """Amplitude as steps (int) on a gridded device, or µA (float) on a continuous one."""
+    if device.continuous_amplitude:
+        if device.max_amplitude_ua is not None and value > device.max_amplitude_ua + _EPS:
+            return device.max_amplitude_ua, Issue("SG101", "error", f"{name} {value:g} µA is above the device's "
+                                                                    f"{device.max_amplitude_ua:g} µA")
+        return value, None
+    steps = device.amp_steps(value)
+    top = device.max_amplitude_steps
+    if steps < 1:
+        return 1, Issue("SG103", "error", f"{name} {value:g} µA is below one amplitude step "
+                                          f"({device.amplitude_step_ua:g} µA)")
+    if top is not None and steps > top:
+        return top, Issue("SG101", "error", f"{name} {value:g} µA is above the device's "
+                                            f"{device.ua(top):g} µA")
+    return steps, None
+
+
+def _grid_width(value: float, device: Device, name: str) -> Tuple[int, Optional[Issue]]:
+    ticks = device.ticks(value)
+    if ticks < device.min_ticks:
+        return device.min_ticks, Issue("SG102", "error", f"{name} {value:g} µs is shorter than the device's "
+                                                         f"{device.us(device.min_ticks):.6g} µs minimum")
+    top = device.max_ticks
+    if top is not None and ticks > top:
+        return top, Issue("SG102", "error", f"{name} {value:g} µs is longer than the device's "
+                                            f"{device.us(top):.6g} µs maximum")
+    return ticks, None
+
+
+def _deliver(pulse: Pulse, device: Device, a1, w1: int, a2, w2: Optional[int], gap: int) -> Delivered:
+    gridded = not device.continuous_amplitude
+    a1_ua = device.ua(a1) if gridded else a1
+    q1 = a1_ua * device.us(w1) * 1e-3
+    target_q1 = pulse.amplitude_ua * pulse.width_us * 1e-3
+    if pulse.biphasic:
+        a2_ua = device.ua(a2) if gridded else a2
+        q2 = a2_ua * device.us(w2) * 1e-3
+        if gridded:  # exact: compare whole steps x whole ticks
+            p1, p2 = a1 * w1, a2 * w2
+            imbalance = abs(p1 - p2) / max(p1, p2)
+            if p1 == p2:
+                q2 = q1  # equal to the last bit, so no float noise in the net charge
+        else:
+            imbalance = abs(q1 - q2) / max(q1, q2)
+            if imbalance < 1e-12:
+                imbalance, q2 = 0.0, q1  # balanced within float precision: report a clean zero net charge
+        ticks = w1 + gap + w2
+    else:
+        a2_ua, q2, imbalance, ticks = None, 0.0, 1.0, w1
+    return Delivered(
+        amplitude_ua=a1_ua,
+        width_us=device.us(w1),
+        biphasic=pulse.biphasic,
+        second_amplitude_ua=a2_ua,
+        second_width_us=device.us(w2) if pulse.biphasic else None,
+        gap_us=device.us(gap),
+        width_ticks=w1,
+        second_width_ticks=w2 if pulse.biphasic else None,
+        gap_ticks=gap,
+        amplitude_steps=a1 if gridded else None,
+        second_amplitude_steps=a2 if (gridded and pulse.biphasic) else None,
+        first_charge_nc=q1,
+        second_charge_nc=q2,
+        net_charge_nc=q1 - q2,
+        imbalance=imbalance,
+        duration_us=device.us(ticks),
+        duration_ticks=ticks,
+        charge_change=(q1 - target_q1) / target_q1,
+    )
+
+
+# --- balanced search ---------------------------------------------------------------------------------------------
+
+def _search(pulse: Pulse, device: Device, a1, w1: int, w2: int, gap: int, max_imbalance: float,
+            keep_first: bool, search_steps: int) -> List[Delivered]:
+    gridded = not device.continuous_amplitude
+    r = 0 if keep_first else search_steps
+    top_ticks = device.max_ticks
+    top_steps = device.max_amplitude_steps
+
+    if gridded:
+        first_amps = [a for a in range(a1 - r, a1 + r + 1) if a >= 1 and (top_steps is None or a <= top_steps)]
+    else:
+        first_amps = [a1]  # continuous: the first phase is kept; the second absorbs the balance
+    first_widths = [w for w in range(w1 - r, w1 + r + 1)
+                    if w >= device.min_ticks and (top_ticks is None or w <= top_ticks)]
+
+    half = max(20, w2 // 2)
+    lo = max(device.min_ticks, w2 - half)
+    hi = w2 + half if top_ticks is None else min(top_ticks, w2 + half)
+    if hi - lo + 1 > MAX_SECOND_WIDTH_CANDIDATES:
+        lo, hi = max(lo, w2 - MAX_SECOND_WIDTH_CANDIDATES // 2), min(hi, w2 + MAX_SECOND_WIDTH_CANDIDATES // 2)
+    second_widths = range(lo, hi + 1)
+
+    step = device.amplitude_step_ua if gridded else 1.0
+    tick = device.time_step_us
+    qmax = device.max_charge_per_phase_nc
+    t_a1, t_w1, t_a2, t_w2 = pulse.amplitude_ua, pulse.width_us, pulse.a2, pulse.w2
+    t_q1 = t_a1 * t_w1 * 1e-3
+
+    pairs = []
+    for fw in first_widths:
+        amps = list(first_amps)
+        if not gridded:  # also try the amplitude that keeps the planned charge on this width
+            keep = t_q1 * 1e3 / (fw * tick)
+            if device.max_amplitude_ua is None or keep <= device.max_amplitude_ua + _EPS:
+                amps.append(keep)
+        pairs += [(fa, fw) for fa in amps]
+
+    scored = []  # (over tolerance, cost, imbalance, candidate)
+    for fa, fw in pairs:
+        a1u = fa * step
+        w1u = fw * tick
+        q1 = a1u * w1u * 1e-3
+        if qmax is not None and q1 > qmax + _EPS:
+            continue
+        dq = abs(q1 - t_q1) / t_q1
+        base = 2 * dq + abs(a1u - t_a1) / t_a1 + abs(w1u - t_w1) / t_w1
+        for sw in second_widths:
+            w2u = sw * tick
+            for sa in _second_amplitudes(fa, fw, sw, device):
+                a2u = sa * step
+                if gridded:
+                    p1, p2 = fa * fw, sa * sw
+                    imb = abs(p1 - p2) / max(p1, p2)
+                else:
+                    q2 = a2u * w2u * 1e-3
+                    imb = abs(q1 - q2) / max(q1, q2)
+                    imb = 0.0 if imb < 1e-12 else imb
+                if qmax is not None and a2u * w2u * 1e-3 > qmax + _EPS:
+                    continue
+                cost = base + abs(a2u - t_a2) / t_a2 + abs(w2u - t_w2) / t_w2
+                scored.append((imb > max_imbalance + _EPS, cost, imb, (fa, fw, sa, sw)))
+    feasible = [s for s in scored if not s[0]]
+    if feasible:
+        feasible.sort(key=lambda s: (s[1], s[2], s[3]))
+        chosen = feasible
+    else:
+        scored.sort(key=lambda s: (s[2], s[1], s[3]))
+        chosen = scored
+    return [_deliver(pulse, device, fa, fw, sa, sw, gap) for _, _, _, (fa, fw, sa, sw) in chosen[:4]]
+
+
+def _second_amplitudes(fa, fw: int, sw: int, device: Device) -> List:
+    if device.continuous_amplitude:
+        a = fa * fw / sw  # exact balance
+        if device.max_amplitude_ua is not None and a > device.max_amplitude_ua + _EPS:
+            return []
+        return [a]
+    x = fa * fw / sw
+    top = device.max_amplitude_steps
+    return [a for a in {math.floor(x), math.ceil(x)} if a >= 1 and (top is None or a <= top)]
+
+
+
+# --- rates -------------------------------------------------------------------------------------------------------
+
+def _rates(rates: Rates, device: Device, best: Delivered, issues: List[Issue]) -> List[RateFit]:
+    out = []
+    for name, hz in rates.items():
+        period = _round_half_up(1e6 / (hz * device.time_step_us))
+        if period < 1:
+            issues.append(Issue("SG302", "error", f"{name} {hz:g} Hz is faster than one time step"))
+            continue
+        delivered = 1e6 / (period * device.time_step_us)
+        change = (delivered - hz) / hz
+        out.append(RateFit(name, hz, period, delivered, change))
+        if abs(change) > 0.001:
+            issues.append(Issue("SG301", "warning", f"{name} {hz:g} Hz is delivered as {delivered:.6g} Hz "
+                                                    f"({change:+.3%}) on a whole number of time steps"))
+        if name != "burst_rate_hz" and best.duration_ticks > period:
+            issues.append(Issue("SG303", "error", f"the pulse ({best.duration_us:.6g} µs) is longer than one "
+                                                  f"period at {name} ({device.us(period):.6g} µs)"))
+        if name != "burst_rate_hz" and device.max_frequency_hz is not None and \
+                delivered > device.max_frequency_hz + _EPS:
+            issues.append(Issue("SG304", "error", f"{name} {delivered:.6g} Hz is above the device's "
+                                                  f"{device.max_frequency_hz:g} Hz"))
+    return out
+
+
+def _moved(pulse: Pulse, d: Delivered, limit: float = 0.10) -> List[Tuple[str, float, float]]:
+    """Planned values that rounding moves by more than limit (a fraction)."""
+    pairs = [("amplitude_ua", pulse.amplitude_ua, d.amplitude_ua), ("width_us", pulse.width_us, d.width_us),
+             ("gap_us", pulse.gap_us, d.gap_us)]
+    if pulse.biphasic:
+        pairs += [("second_amplitude_ua", pulse.a2, d.second_amplitude_ua),
+                  ("second_width_us", pulse.w2, d.second_width_us)]
+    return [(n, w, g) for n, w, g in pairs if w > 0 and abs(g - w) / w > limit]
+
+
+def _clean(x: Optional[float]) -> Optional[float]:
+    """Drop float noise such as 100.00000000000001 in exported values."""
+    if x is None:
+        return None
+    r = round(x, 9)
+    return int(r) if r == int(r) else r

stimgrid/loader.py

@@ -0,0 +1,129 @@
+"""Read a fit request (format version 1). Errors name the exact place, e.g. pulse.width_us.
+
+{
+  "stimgrid": 1,
+  "device": {"preset": "intan-rhs2116", "step_ua": 0.1, "sample_rate_hz": 30000},
+  "pulse": {"amplitude_ua": 7.3, "width_us": 117, "second_amplitude_ua": 1.9, "second_width_us": 450},
+  "rates": {"frequency_hz": 40},
+  "max_imbalance": 0,
+  "keep_first": false
+}
+
+A device is a preset (with its options, plus any field to override) or a full description:
+{"name": "my stimulator", "time_step_us": 10, "amplitude_step_ua": 0.5, "max_amplitude_ua": 100}
+"""
+
+from __future__ import annotations
+
+import inspect
+import json
+import math
+import sys
+from dataclasses import fields
+from pathlib import Path
+from typing import Any, Dict, Tuple, Union
+
+from .devices import PRESETS, Device, override, preset
+from .fit import Pulse, Rates
+
+FORMAT_VERSION = 1
+DEVICE_FIELDS = tuple(f.name for f in fields(Device))
+TOP_FIELDS = ("stimgrid", "device", "pulse", "rates", "max_imbalance", "keep_first", "search_steps")
+
+
+class InputError(ValueError):
+    """The request is not valid. The message starts with where the problem is."""
+
+
+def from_dict(data: Any) -> Tuple[Pulse, Device, Rates, Dict[str, Any]]:
+    """Returns the pulse, the device, the rates and the fit options."""
+    _object(data, "request")
+    _known(data, TOP_FIELDS, "request")
+    if data.get("stimgrid") != FORMAT_VERSION:
+        raise InputError(f"stimgrid: must be {FORMAT_VERSION} (the format version), got {data.get('stimgrid')!r}")
+    for key in ("device", "pulse"):
+        if key not in data:
+            raise InputError(f"request: missing '{key}'")
+    device = device_from_dict(data["device"], "device")
+    pulse = _build(Pulse, data["pulse"], "pulse")
+    rates = _build(Rates, data.get("rates", {}), "rates")
+    options = {}
+    if "max_imbalance" in data:
+        v = data["max_imbalance"]
+        if not (_number(v) and 0 <= v < 1):
+            raise InputError(f"max_imbalance: must be a number from 0 up to (not including) 1, got {json.dumps(v)}")
+        options["max_imbalance"] = float(v)
+    if "keep_first" in data:
+        if not isinstance(data["keep_first"], bool):
+            raise InputError("keep_first: must be true or false")
+        options["keep_first"] = data["keep_first"]
+    if "search_steps" in data:
+        v = data["search_steps"]
+        if not (isinstance(v, int) and not isinstance(v, bool) and 0 <= v <= 20):
+            raise InputError("search_steps: must be a whole number from 0 to 20")
+        options["search_steps"] = v
+    return pulse, device, rates, options
+
+
+def device_from_dict(spec: Any, path: str = "device") -> Device:
+    _object(spec, path)
+    if "preset" in spec:
+        name = spec["preset"]
+        if name not in PRESETS:
+            raise InputError(f"{path}.preset: unknown preset {name!r}; known: {', '.join(sorted(PRESETS))}")
+        option_names = tuple(inspect.signature(PRESETS[name]).parameters)
+        _known(spec, ("preset",) + option_names + DEVICE_FIELDS, path)
+        options = {k: spec[k] for k in option_names if k in spec}
+        changes = {k: spec[k] for k in DEVICE_FIELDS if k in spec}
+        for k, v in {**options, **changes}.items():
+            if k not in ("name", "source", "note") and not _number(v):
+                raise InputError(f"{path}.{k}: must be a number, got {json.dumps(v)}")
+        base = _wrap(path, lambda: preset(name, **options))
+        return _wrap(path, lambda: override(base, **changes))
+    _known(spec, DEVICE_FIELDS, path)
+    if "name" not in spec or "time_step_us" not in spec:
+        raise InputError(f"{path}: give a 'preset', or at least 'name' and 'time_step_us'")
+    return _build(Device, spec, path)
+
+
+def load(source: Union[str, Path]) -> Tuple[Pulse, Device, Rates, Dict[str, Any]]:
+    """Read a request from a file path, or from stdin when source is '-'."""
+    try:
+        if str(source) == "-":
+            data = json.load(sys.stdin)
+        else:
+            with open(source, encoding="utf-8") as fh:
+                data = json.load(fh)
+    except json.JSONDecodeError as exc:
+        raise InputError(f"input: not valid JSON (line {exc.lineno}, column {exc.colno}: {exc.msg})") from None
+    return from_dict(data)
+
+
+def _build(cls, spec: Any, path: str):
+    _object(spec, path)
+    _known(spec, tuple(f.name for f in fields(cls)), path)
+    return _wrap(path, lambda: cls(**spec))
+
+
+def _number(v: Any) -> bool:
+    return isinstance(v, (int, float)) and not isinstance(v, bool) and math.isfinite(v)
+
+
+def _object(value: Any, path: str) -> None:
+    if not isinstance(value, dict):
+        raise InputError(f"{path}: must be an object")
+
+
+def _known(spec: Dict[str, Any], allowed: Tuple[str, ...], path: str) -> None:
+    unknown = sorted(set(spec) - set(allowed))
+    if unknown:
+        raise InputError(f"{path}: unknown field(s) {', '.join(unknown)}")
+
+
+def _wrap(path: str, make):
+    try:
+        return make()
+    except InputError:
+        raise
+    except (ValueError, TypeError) as exc:
+        raise InputError(f"{path}: {exc}") from None

stimgrid-0.2.0.dist-info/METADATA

@@ -0,0 +1,317 @@
+Metadata-Version: 2.4
+Name: stimgrid
+Version: 0.2.0
+Summary: Fit stimulation pulses to what a stimulator can actually produce, and find the nearest exactly charge-balanced pulse.
+Author: Sanjeev Muthusamy
+License: MIT
+Project-URL: Homepage, https://github.com/sanjeevmuthusamy/stimgrid
+Project-URL: Issues, https://github.com/sanjeevmuthusamy/stimgrid/issues
+Keywords: neuroscience,electrophysiology,neurostimulation,electrical stimulation,microstimulation,charge balance,charge-balanced,biphasic pulse,asymmetric pulse,stimulation safety,multi-electrode array,MEA,microelectrode,neural interface,brain-computer interface,DAC quantization,Intan,RHS2116,Multi Channel Systems,STG4000,STG5,Tucker-Davis Technologies,IZ2,Cortical Labs
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# stimgrid
+
+Your stimulator cannot produce every pulse you write down. It sets current in fixed steps and timing on
+a fixed clock, so every value gets rounded. For an asymmetric pulse (for example a short strong first
+phase and a long weak recharge phase) that rounding quietly breaks the charge balance you designed. A
+rate of 130 Hz may also become 129.87 Hz.
+
+stimgrid shows what your device will actually deliver, and finds the nearest pulse on the device's grid
+whose two phases carry exactly equal charge. Pure Python, no dependencies.
+
+For electrical neurostimulation and microstimulation on multi-electrode arrays (MEAs), microelectrodes
+and neural interfaces, with presets for the Intan RHS2116, Multi Channel Systems STG4000 and STG5,
+Tucker-Davis Technologies IZ2 and Cortical Labs CL, and support for any other current-controlled
+stimulator from its current and timing steps.
+
+**Research use only.** stimgrid works from the resolution you give it (or a preset's published
+figures). Check the result on your own hardware and settings.
+
+## Install
+
+Requires Python 3.9 or newer, and nothing else.
+
+```bash
+pip install git+https://github.com/sanjeevmuthusamy/stimgrid
+```
+
+Or from a downloaded copy, inside the `stimgrid` folder:
+
+```bash
+pip install .
+```
+
+This gives you the `stimgrid` command. You can also run it without installing, from the folder, as
+`PYTHONPATH=src python -m stimgrid ...`.
+
+## Quick start
+
+1. **Find your device.** `stimgrid devices` lists the built-in presets and where their figures come
+   from. If yours is not there, give its own steps instead (see [Devices](#devices)).
+2. **Check your pulse.** Give the first phase, the second phase and the rate:
+
+   ```bash
+   stimgrid quick --device mcs-stg4000 --amplitude-ua 7.3 --width-us 117 \
+     --second-amplitude-ua 1.9 --second-width-us 450 --frequency-hz 130
+   ```
+
+3. **Read the result** (see [Reading the output](#reading-the-output)). Use the `balanced` pulse, or one
+   of the options, in your stimulation software.
+4. **Save it for later or for a lab mate** as a [request file](#request-files), and rerun it with
+   `stimgrid fit my_pulse.json`.
+
+Leave out `--second-amplitude-ua` and `--second-width-us` for a symmetric pulse; the second phase then
+copies the first.
+
+## Reading the output
+
+For the quick start command above:
+
+```
+device: mcs-stg4000 (1.6 mA version): 20 µs time steps, 0.2 µA steps, max 1600 µA
+  plan      7.3 µA x 117 µs | gap 0 µs | 1.9 µA x 450 µs
+  rounded   7.4 µA x 120 µs | gap 0 µs | 2 µA x 460 µs
+            charge 0.888 nC (+3.97% vs plan), net -0.032 nC, imbalance 3.4783%
+  balanced  7.2 µA x 120 µs | gap 0 µs | 1.8 µA x 480 µs
+            charge 0.864 nC (+1.16% vs plan), net 0 nC, imbalance 0.0000%
+  option 1  7 µA x 120 µs | gap 0 µs | 2 µA x 420 µs
+            charge 0.84 nC (-1.65% vs plan), net 0 nC, imbalance 0.0000%
+  ...
+  rate      frequency_hz 130 Hz -> 129.87 Hz (385 steps per period, -0.100%)
+
+WARNING SG201 simple rounding leaves the pulse unbalanced (imbalance 3.4783%, net -0.032 nC per pulse)
+
+best pulse: {"amplitude_ua": 7.2, "width_us": 120, "second_amplitude_ua": 1.8, "second_width_us": 480}
+result: OK
+```
+
+| Line | Meaning |
+|---|---|
+| `device` | The grid being used: time step, current step and maximum current |
+| `plan` | The pulse you asked for: first phase, gap, second phase |
+| `rounded` | What the device delivers if you type your plan in as it is |
+| `balanced` | The closest pulse whose two phases carry exactly equal charge. **Use this one** |
+| `option 1-3` | Other exactly balanced pulses, next closest first |
+| `charge` | Charge in the first phase, and how far it moved from your plan |
+| `net` | Charge left on the electrode by every pulse; 0 means balanced |
+| `imbalance` | The difference between the two phases' charges, as a share of the larger one |
+| `rate` | The rate you asked for, and the rate the device's clock really gives |
+| `WARNING` / `ERROR` | Findings, explained in [Findings](#findings) |
+| `best pulse` | The pulse to use, in a form you can paste into a file or program |
+| `result` | `OK`, or `ERROR` if the pulse breaks a device limit or cannot be balanced |
+
+Here the planned pulse would leave 0.032 nC on the electrode with every pulse; the balanced one leaves
+none and keeps charge per phase within 1.2% of the plan.
+
+## Another example: Intan RHS2116
+
+An asymmetric pulse on an Intan RHS2116 with 0.1 µA steps, driven at 30,000 samples/s:
+
+```bash
+stimgrid quick --device intan-rhs2116 --step-ua 0.1 --sample-rate-hz 30000 \
+  --amplitude-ua 7.3 --width-us 117 --second-amplitude-ua 1.9 --second-width-us 450 --frequency-hz 40
+```
+
+```
+device: intan-rhs2116 (step 0.1 µA, 30000 samples/s): 33.3333 µs time steps, 0.1 µA steps, max 25.5 µA
+  plan      7.3 µA x 117 µs | gap 0 µs | 1.9 µA x 450 µs
+  rounded   7.3 µA x 133.333 µs | gap 0 µs | 1.9 µA x 466.667 µs
+            charge 0.97333 nC (+13.96% vs plan), net 0.08667 nC, imbalance 8.9041%
+  balanced  7.2 µA x 100 µs | gap 0 µs | 1.8 µA x 400 µs
+            charge 0.72 nC (-15.70% vs plan), net 0 nC, imbalance 0.0000%
+  option 1  7.2 µA x 133.333 µs | gap 0 µs | 1.8 µA x 533.333 µs
+            charge 0.96 nC (+12.40% vs plan), net 0 nC, imbalance 0.0000%
+  ...
+WARNING SG201 simple rounding leaves the pulse unbalanced (imbalance 8.9041%, net 0.08667 nC per pulse)
+WARNING SG203 the balanced pulse changes charge per phase by -15.7%
+```
+
+Simple rounding would leave 0.087 nC behind on every pulse. stimgrid lists exactly balanced pulses
+instead, closest to your plan first, and warns when the grid forces charge per phase to move.
+
+## How it works
+
+1. **Rounded.** Each amplitude, phase width and gap is rounded (halves up) to the device's steps and
+   clamped to its ranges. This is what you get if you type the plan in and let the device round it.
+2. **Balanced.** stimgrid searches small changes to both phases, mostly the second phase's width and
+   amplitude, the usual balancing knobs. On a gridded device, balance is checked exactly, as whole
+   current steps times whole time steps, so "balanced" means equal to the last bit. On a device with
+   continuous amplitude it also tries the first-phase amplitude that keeps your planned charge exactly.
+3. **Ranking.** Exactly balanced candidates are ranked by closeness to your plan, with first-phase charge
+   counted double because it sets the effect. The best and three alternatives are shown.
+4. **Rates.** Each rate is rounded to a whole number of time steps per period, and the delivered rate is
+   reported.
+
+## Command options
+
+`stimgrid quick` takes the pulse as flags. Amplitudes are in µA, times in µs, rates in Hz.
+
+| Flag | Meaning |
+|---|---|
+| `--device NAME` | A preset from `stimgrid devices` |
+| `--step-ua`, `--sample-rate-hz`, `--range-ua` | Preset settings (see [Devices](#devices)) |
+| `--time-step-us`, `--amplitude-step-ua` | Your own device's steps, without a preset (or to override one) |
+| `--max-amplitude-ua`, `--max-charge-per-phase-nc` | Your own device's limits |
+| `--amplitude-ua`, `--width-us` | First phase (required) |
+| `--second-amplitude-ua`, `--second-width-us` | Second phase (defaults to the same as the first) |
+| `--gap-us` | Gap between the phases |
+| `--monophasic` | One phase only |
+| `--frequency-hz`, `--intra-burst-hz`, `--burst-rate-hz` | Rates to check against the time grid |
+| `--keep-first` | Keep the rounded first phase as it is; balance with the second phase only |
+| `--max-imbalance 0.001` | Accept up to 0.1% imbalance as balanced (the default is exact) |
+
+Both `quick` and `fit` also take:
+
+| Flag | Meaning |
+|---|---|
+| `--format text` | Readable report (the default) |
+| `--format json` | The full report as JSON, for scripts |
+| `--format pulse` | Only the best pulse as JSON |
+| `--strict` | Treat warnings as failures (exit code 1), for automated checks |
+
+`stimgrid --help` and `stimgrid quick --help` list them too.
+
+## Devices
+
+| Preset | Time step | Amplitude | Source |
+|---|---|---|---|
+| `intan-rhs2116` | 1 / sample rate (`--sample-rate-hz`, default 30,000) | `--step-ua` of 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5 or 10 µA, up to 255 steps | Intan RHS2116 datasheet |
+| `cortical-labs-cl` | 20 µs | continuous (no step published), up to 3 µA, 3 nC per phase | Cortical Labs CL API docs (StimDesign) |
+| `mcs-stg4000` | 20 µs, up to 25 kHz | `--range-ua 1600`: 0.2 µA steps; `--range-ua 16000`: 2 µA steps | MCS STG 4002/4004/4008 datasheets |
+| `mcs-stg5` | 5 µs, up to 100 kHz | `--range-ua 160`: 0.1 µA; `1600`: 1 µA; `16000`: 10 µA steps | MCS STG5 brochure |
+| `tdt-iz2` | 1 / RZ sample rate (`--sample-rate-hz`, default 24,414.0625) | continuous (no step published); `--range-ua 300` (IZ2, IZ2M) or `3000` (IZ2H, IZ2MH) | TDT IZ2 manual, IZ2M/IZ2MH spec sheet |
+
+All presets are current mode. The MCS range is the model version you bought (STG4000) or the range you
+select (STG5). The STG4000 160 µA version is left out because its official datasheet could not be
+confirmed.
+
+**Not included yet**, because the vendor does not publish a current step or a timing step:
+
+| Device | Published | Missing |
+|---|---|---|
+| Axion Maestro Pro / Edge | ±250 µA, ±1.2 V, phase at least 100 µs | current step, time step |
+| MaxWell MaxOne / MaxTwo | 32 stimulation units, ±1.0 V | current range and step, time step |
+| Blackrock CereStim | phase 44–65,535 µs, 4 Hz–5 kHz, 100 µA steps (macro model) | micro model step, time step |
+| A-M Systems 4100 | 100 mA with 1 µA resolution, pulses from 1 µs | time step |
+
+If you have one of these, describe it with your own numbers (below), or send the values from your
+manual and they can become a preset.
+
+`stimgrid devices` prints each preset's source. The RHS2116 has no pulse timers; the host sets every
+edge, so its timing grid depends on your host software. Any other stimulator can be described by its
+own numbers:
+
+```bash
+stimgrid quick --time-step-us 10 --amplitude-step-ua 0.5 --max-amplitude-ua 100 \
+  --amplitude-ua 20 --width-us 105 --second-amplitude-ua 4 --second-width-us 520
+```
+
+Fields: `time_step_us` (required), `amplitude_step_ua` (leave out for continuous), `max_amplitude_ua`,
+`min_phase_us`, `max_phase_us`, `max_charge_per_phase_nc`, `max_frequency_hz`.
+
+## Request files
+
+```json
+{
+  "stimgrid": 1,
+  "device": {"preset": "intan-rhs2116", "step_ua": 0.1, "sample_rate_hz": 30000},
+  "pulse": {"amplitude_ua": 7.3, "width_us": 117, "second_amplitude_ua": 1.9, "second_width_us": 450},
+  "rates": {"frequency_hz": 40},
+  "max_imbalance": 0,
+  "keep_first": false
+}
+```
+
+```bash
+stimgrid fit examples/intan_asymmetric.json
+stimgrid fit examples/intan_asymmetric.json --format json
+cat request.json | stimgrid fit - --format pulse
+```
+
+A preset takes its options (`step_ua`, `sample_rate_hz` or `range_ua`, as in the table) and any device
+field to override, for example `{"preset": "intan-rhs2116", "step_ua": 0.1, "max_amplitude_ua": 10}` or
+`{"preset": "mcs-stg5", "range_ua": 160}`. Invalid input names the exact
+place, for example `pulse: width_us must be a positive number`.
+
+`--format pulse` prints only the best pulse, in the common shape (`amplitude_ua`, `width_us`,
+`second_amplitude_ua`, `second_width_us`, `gap_us`), ready to paste into a protocol file or another tool.
+
+## Findings
+
+| Code | Level | Meaning |
+|---|---|---|
+| SG101 | error | An amplitude is above the device's maximum |
+| SG102 | error | A phase width is outside the device's range |
+| SG103 | error | An amplitude is below one current step |
+| SG104 | error | Charge per phase is above the device's maximum |
+| SG105 | warning | The interphase gap rounds to zero |
+| SG106 | warning | Rounding moves a value by more than 10% |
+| SG201 | warning | Simple rounding leaves the pulse unbalanced |
+| SG202 | error | No balanced pulse was found within the search and the device's limits |
+| SG203 | warning | The balanced pulse changes charge per phase by more than 5% |
+| SG301 | warning | A rate changes by more than 0.1% on whole periods |
+| SG303 | error | The pulse is longer than one period at that rate |
+| SG304 | error | A rate is above the device's maximum |
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Fitted with no errors (and no warnings, with `--strict`) |
+| 1 | Errors (or warnings, with `--strict`) |
+| 2 | Bad input or usage |
+| 3 | Internal error |
+
+## From Python
+
+```python
+from stimgrid import Pulse, Rates, fit, intan_rhs2116
+
+report = fit(Pulse(7.3, 117, second_amplitude_ua=1.9, second_width_us=450),
+             intan_rhs2116(step_ua=0.1, sample_rate_hz=30000), Rates(frequency_hz=40))
+print(report.balanced.as_pulse(), report.balanced.imbalance)
+```
+
+## Limits of this tool
+
+- It models one pulse shape: rectangular phases with an optional gap. It does not model DAC settling,
+  electrode impedance, channel-to-channel mismatch or the RHS2116's trim settings.
+- Rates are assumed to fall on the same time grid as phase widths.
+- Continuous amplitude means the device's real amplitude resolution is unknown; the reported amplitude
+  may need rounding again on the hardware.
+
+## Citing
+
+If you use stimgrid in published work, please cite it. GitHub's "Cite this repository" button gives the
+reference from `CITATION.cff`:
+
+> Muthusamy S. stimgrid (version 0.2.0) [Computer software]. https://github.com/sanjeevmuthusamy/stimgrid
+
+## Tests
+
+```bash
+python -m unittest discover -s tests
+```
+
+## Licence
+
+MIT. See `LICENSE`.

stimgrid-0.2.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+stimgrid/__init__.py,sha256=IMcTZKrrZziADveL96iDI-LVSkbTt-5Pg2FEAe00iyQ,798
+stimgrid/__main__.py,sha256=E6Gls0DNz8GQK2K-kOUIx8cYhgANW_CH54VKrfCfs14,52
+stimgrid/cli.py,sha256=ABKI2u09bD1OUpSQRLsED3v5nzoxrqlkKAnV2UH21nc,8466
+stimgrid/devices.py,sha256=04jwECK-ktT-3bgL5xmvbgIhj353g9bNTqmsHklUeQo,9983
+stimgrid/fit.py,sha256=aldqvnhjTrGEjysNHkQbtrmw1CEQlCYehmYNA0gHacI,18311
+stimgrid/loader.py,sha256=uaJFMOsyWpxlvOr3kkwGJ-w8rVr3EMoL_e-nZpvrwhA,5072
+stimgrid-0.2.0.dist-info/licenses/LICENSE,sha256=wNrHtPRtCWvdGS6BuEZmngo6Pp7PuCcNOr9zfjZUW4w,1074
+stimgrid-0.2.0.dist-info/METADATA,sha256=JJmHIsaOAyI_sFuwdu0IsCBabhagkioyOOut0eOay7Y,15107
+stimgrid-0.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+stimgrid-0.2.0.dist-info/entry_points.txt,sha256=sjVCWjbiqavEUe8f644RYMbQKz9hXvofu-K7ENpVBBY,47
+stimgrid-0.2.0.dist-info/top_level.txt,sha256=GB5qmuIhUG2qepLTEFUWSWx-hr-AdAl1kAKm4zSNFoc,9
+stimgrid-0.2.0.dist-info/RECORD,,

stimgrid-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

stimgrid-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+stimgrid = stimgrid.cli:main

stimgrid-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sanjeev Muthusamy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stimgrid-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+stimgrid