Metadata-Version: 2.4
Name: cicadc
Version: 0.2.0
Summary: Interactive PySide6 + manim demonstration of how an ADC works
Author-email: Carsten Wulff <carsten@wulff.no>
License: MIT
Project-URL: Homepage, https://github.com/wulffern/cicadc
Project-URL: Bug Tracker, https://github.com/wulffern/cicadc/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Topic :: Education
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: manim
Requires-Dist: PySide6
Requires-Dist: click
Dynamic: license-file

# cicadc

An interactive desktop program that demonstrates how an analog-to-digital
converter (ADC) works. It shows two side-by-side panels rendered with
[manim](https://www.manim.community/) inside a [PySide6](https://doc.qt.io/qtforpython-6/)
window:

- **Left panel (analog)** - the analog signal drawn as a path that scrolls past
  "now" (the middle line), with the future at the top and the past at the
  bottom. A blue car drives along the (clean) analog signal and turns to follow
  the path. A "shadow" car marks the converter output at now - pale green when a
  decimator is active (the coarse quantizer/modulator output) or white/gray
  otherwise (the digital output). Noise is added before the converter, not on
  the displayed analog curve.
- **Right panel (digital)** - the digital signal as a sample-and-hold staircase.
  Pale green is the coarse quantizer/modulator output and white/gray is the
  decimated/filtered digital output (normalised to unity gain at the signal
  frequency). A white/gray car follows the digital output, trailing by the
  filter's group delay so it lands back on the analog curve (delay-compensated).

The ADC can run as a plain Nyquist-rate uniform quantizer or as a 1st- or
2nd-order **sigma-delta** modulator (with optional dither); a sigma-delta
bitstream is decimated by a cascaded sinc^N (CIC-style) moving-average filter
matched to the modulator order.

## Project layout

```
src/cicadc/          package (src layout, mirrors cicwave)
  cli.py             click console entry point (`cicadc`)
  app.py             QApplication bootstrap
  main_window.py     PySide6 window + controls
  manim_scene.py     offscreen manim renderer
  signal_source.py   analog signal model (sinusoid + noise)
  quantizer.py       N-bit quantizer
  render_widget.py   Qt widget + animation loop
  assets/car.png     car sprite
tests/unittests/     unittest suite
```

## Requirements

- Python 3.9-3.13 (manim does not yet support 3.14). A `python3.12` venv is used
  by the setup steps below.
- A working manim install (Cairo backend). On macOS you may need the system
  libraries `pkg-config cairo pango` via Homebrew if the wheels do not cover your
  platform.

## Setup

```bash
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e .          # or: pip install -r requirements.txt
```

`make dev-install` runs the editable install for you.

## Run

```bash
cicadc                   # installed console script
# or, from a checkout without installing:
python main.py
```

## Controls

- **Frequency / Amplitude** - the input sinusoid (sliders; amplitude is a fraction of full scale).
- **Speed** - how fast the signal scrolls past "now".
- **Bits** - resolution of the quantizer / modulator.
- **Sample period** - the ADC sample clock interval.
- **Noise** - additive noise amplitude, applied before the converter.
- **ADC type** - Nyquist quantizer, or 1st-/2nd-order sigma-delta modulator.
- **Dither** - deterministic dither for the sigma-delta quantizer (ΣΔ modes only).
- **Avg** - decimation/averaging length on the digital output (1 = off); uses a
  sinc^N cascade matched to the ADC type.
- **Play / Pause** - start or stop the animation.

A signal-chain bar above the view highlights the active path
(Analog → Noise → Quantizer/ΣΔ → Filter → Digital).

## Development

```bash
make test     # run unit tests
make check    # import and print version
make lint     # ruff (if installed)
make build    # build wheel + sdist
```

## Acknowledgements

Big thanks to **Domen Visnar** for the idea behind this project!

## Rendering

The manim scene is rasterised offscreen (Cairo) and painted into the Qt widget.
Cost scales with pixel count, so resolution and frame rate trade off; the
default is 1280x896 at 30 fps, with the static scenery cached so only the moving
content is rebuilt each frame.

## Status

Single sinusoid input, adjustable bit depth, noise, Nyquist and 1st-/2nd-order
sigma-delta ADCs, a sinc^N decimation filter with delay compensation, and the
signal-chain bar are implemented. Random / multi-sinusoid inputs and a
configurable bandwidth filter are planned follow-ups.
