pycircuit-new 0.1.1
Lightweight circuit simulator (single-file)
License: MIT
Requires Python: >=3.8

# pycircuit_new

Lightweight single-file circuit simulator using Modified Nodal Analysis (MNA).

`pycircuit_new` is a compact, single-file Python library for building and simulating simple electrical networks made of resistors, LEDs, ideal voltage sources, and capacitors. It focuses on clarity and a small API surface so you can quickly add circuits, run DC or transient simulations, and inspect voltages and currents.

---

## Highlights

- Single-file library, easy to embed or publish as a package.
- DC solver using Modified Nodal Analysis. Works with one ideal voltage source per circuit.
- Time-domain transient simulation with companion models for capacitors, supporting backward Euler and trapezoidal integration.
- Simple component classes and a user-friendly `Circuit` wrapper for common tasks.
- Optional schematic drawing using `schemdraw` for quick visualisation.

---

## Requirements

- Python 3.8 or newer.
- Runtime dependencies:

  - `numpy`
  - `schemdraw` (only required if you intend to draw diagrams)

Install dependencies with pip:

```bash
pip install numpy schemdraw
```

If you publish the package to PyPI, runtime dependencies should be declared in the package metadata.

---

## Quick start

Example: build and simulate a simple series circuit with a 5 V source and a 100 ohm resistor.

```python
from pycircuit_new import Circuit, Resistor, PowerSource

c = Circuit()
vs = PowerSource(5.0, [1, 0])    # voltage from node 1 to ground (0)
r = Resistor(100.0, [1, 0])      # 100 ohm between node 1 and ground

c.add(vs)
c.add(r)

c.simulate()                      # run DC simulation
print('Node voltages:', c._node_voltage_cache)  # or use public helpers
print('Source current:', c.calculate_current())
print('Voltage across resistor:', c.measure_voltage([1, 0]))
```

The `simulate()` method populates component states with currents and voltage drops. `calculate_current()` returns the current through the power source.

---

## Transient simulation

Run a time-domain simulation with capacitors using a companion model. The `Circuit.transient_simulate` method returns time points, node histories, and component current histories.

```python
from pycircuit_new import Circuit, PowerSource, Resistor, Capacitor

c = Circuit()
c.add(PowerSource(10.0, [1, 0]))
c.add(Resistor(1000.0, [1, 0]))
c.add(Capacitor(1e-6, [1, 0], initial_voltage=0.0))

times, node_history, comp_history = c.transient_simulate(t_stop=0.01, dt=1e-4, integration_method='backward_euler')
# node_history maps node -> numpy array of voltages at each time step
```

Use `integration_method='trapezoidal'` for higher accuracy when appropriate.

---

## API reference (compact)

### Key classes

- `ComponentSpec(kind, value, nodes, id=None)`
  Immutable specification for a component. `kind` is one of `'R'`, `'LED'`, `'V'`, `'C'`.

- `ComponentState`
  Mutable per-component simulation state. Holds `current` and `voltage_drop`.

- `Component`
  Abstract base class for all components. Use concrete classes below.

- `Resistor(resistance, connections, id=None)`
  Resistor component. Methods: `set_current`, `calculate_voltage_drop`, `calculate_power`.

- `LED(resistance, connections, forward_voltage=2.0, id=None)`
  Simplified LED model with a forward voltage offset. Methods similar to `Resistor`.

- `PowerSource(voltage, connections, id=None)`
  Ideal DC voltage source.

- `Capacitor(capacitance, connections, initial_voltage=0.0, id=None)`
  Capacitor that stores previous voltage for transient simulation.

- `Circuit()`
  Top-level simulator and container for components. Important methods:

  - `add(component)` add a component to the circuit.
  - `simulate()` run DC analysis and update component states.
  - `calculate_current()` return total source current.
  - `calculate_total_resistance()` approximate or compute equivalent resistance.
  - `measure_voltage([n1, n2])` measure voltage difference between nodes.
  - `measure_current([n1, n2])` measure current through a component between nodes.
  - `draw_circuit_diagram()` draw a simple left-to-right schematic using `schemdraw`.
  - `transient_simulate(t_stop, dt, record_nodes=None, integration_method='backward_euler')` perform transient run.
  - `compare_integration_methods(t_stop, dt, node_to_compare=2)` helper to compare BE vs trapezoidal.

Also top-level functions `solve_mna` and `solve_mna_time_step` are available for advanced use.

---

## Notes and limitations

- The LED model is linearized and uses a forward-voltage offset. It is not a full diode I-V model.
- Only a single ideal voltage source is supported in the DC solver. Additional sources will raise an error.
- The DC solver treats capacitors as open circuits. Use transient simulation to include capacitors.
- The library does not currently include advanced netlist parsing or automated layout for drawing.

---

## Development and testing

Contributions are welcomed in these areas:

- Run the existing examples interactively to validate behavior.
- Consider adding unit tests for: stamping operations, small circuits with known solutions, transient responses for RC circuits.

---

## License

MIT Licence

---

## Contributing

Contributions and bug reports are welcome. Open a ticket or a pull request with a small, focused change. Add tests for new features.

---

## Contact

```
Author: Ege Güvener
Email: egeguvener0808@gmail.com
```