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:

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.

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.

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