How hausen/circuit-simulator works
Project Type and Purpose
• This is a standalone Java circuit-simulator (also usable as a browser applet) based on Paul Falstad’s original work, extended with import/export, file saving, bundled circuit examples, and UI improvements.
• It is not a web service or microservice – it is a desktop/applet GUI application that simulates electrical circuits in real time.
File Structure Analysis
• Top-level:
• README.md, .gitignore, src/Makefile, Manifest.txt – build and metadata
• src/*.java – core Java sources
• src/circuits/*.txt – sample circuit definitions bundled as resources
• Key source packages/areas:
• Core engine: Circuit.java, CircuitElm.java and its ∼70 subclasses (ResistorElm, CapacitorElm, GateElm, etc.), CircuitNode/Link, CircuitLayout
• Simulation loop & orchestration: CirSim.java, CircuitCanvas.java, Scope.java
• UI/Controller: EditDialog*.java, ImportExport*.java, EditOptions, ImportExportDialogFactory
• Persistence/Resources: dump format (text), circuits/*.txt, importCircuit/exportCircuit hooks for applet integration
Architectural Patterns & Design Principles
• Polymorphism/Factory: each circuit element is a subclass of CircuitElm, selected and instantiated dynamically
• MVC-like separation:
• Model = Circuit, CircuitElm hierarchy, CircuitNode/Link, CircuitLayout
• View = CircuitCanvas (renders the model), Scope (oscilloscope view)
• Controller = CirSim main class, EditDialog*/ImportExportDialog* classes, UI event handlers
• Resource-bundling: circuits/*.txt loaded at startup into the “Circuit” menu
Main Components
a. Java Runtime Environment
b. Application Entrypoints
• CirSim (main for desktop JAR)
• Circuit (applet)
c. Simulation Engine (Model)
• Circuit (circuit state & node graph)
• CircuitElm subclasses (components)
• CircuitNode, CircuitNodeLink, CircuitLayout
d. Presentation Layer (View & Controller)
• CircuitCanvas (rendering engine)
• Scope (real-time waveform display)
• EditDialog*/EditInfo/EditOptions (component editing UI)
• ImportExportDialog*/Factory (load/save dialogs)
e. Persistence & Resources
• circuits/*.txt (bundled circuit definitions)
• exportCircuit / importCircuit JavaScript hooks (applet mode)
• File system (application mode)
f. Build & Packaging
• Makefile, javac, jar with Manifest.txt
Relationships and Data Flows
• User interacts with UI components (CircuitCanvas, dialogs) → Controller (CirSim, EditDialog*, ImportExportDialog*)
• Controller invokes Simulation Engine APIs (Circuit.addNode, CircuitElm.step, etc.)
• Simulation Engine updates circuit state → View components (CircuitCanvas.redraw(), Scope.update())
• Persistence module reads/writes text dumps:
• On load: ImportExportDialog → Parser → Circuit & CircuitElm instances
• On save: Circuit.dump() → Exporter → file or JavaScript callback
• Resource loader at startup scans circuits/*.txt → registers menu entries → clicking loads via same import path
Important Details to Capture
• The polymorphic factory pattern for element instantiation
• The MVC-style interaction and data-flow separation
• Dual operation modes: desktop (file system) vs. applet (JavaScript hooks)
• Bundled circuit resources and how they plug into the import pipeline
• Real-time rendering (CircuitCanvas) vs. snapshot export (dump format)