Circuit Simulator API

Overview

URL: https://api.marsthelimit.com/simulate

Authentication: API Key required via header ("Authorization": "Bearer YOUR_API_KEY")

Supported format: JSON

The Circuit Simulator API lets you:

• Simulate DC circuits (resistors, voltage sources, current sources, op-amps, BJTs)
• Simulate AC circuits (resistors, capacitors, inductors, voltage sources)
• Get node voltages and branch currents for any circuit topology
• Model op-amp and BJT transistor behavior using standard small-signal models

All requests are made via a JSON payload.

Request Method

POST https://api.marsthelimit.com/simulate

Authentication: API Key required via header ("Authorization": "Bearer YOUR_API_KEY")

Body: JSON

Request Body

1{
2  "nodes": ["gnd", "n1", "n2"],
3  "components": [...],
4  "analysis": {
5    "type": "dc"
6  }
7}

Fields

Nodes

Nodes are the named connection points in your circuit, like the dots on a circuit diagram where wires meet. Every circuit must include "gnd" as the ground reference (always 0V). All other nodes can be named anything you like.

1"nodes": ["gnd", "n1", "n2", "n_out"]

Analysis Types

DC Analysis

Solves for steady-state voltages. Use for circuits powered by batteries or constant voltage/current sources.

1"analysis": {"type": "dc"}

AC Analysis

Solves for voltages at a specific frequency. Use for filters, amplifiers, and any circuit with capacitors or inductors. Returns magnitude and phase at each node.

1"analysis": {"type": "ac", "frequency": 1000}

Component Types

Every component has a type field and an optional name field. The name field labels the component in the response. If omitted, the API automatically generates one (e.g. vsource_0).

Resistor

A resistor between two nodes.

1{
2  "type": "resistor",
3  "name": "R1",
4  "n1": "n1",
5  "n2": "n2",
6  "value": 1000
7}

Voltage Source

A fixed voltage source such as a battery. This introduces a branch current variable in the solver.

1{
2  "type": "vsource",
3  "name": "V_battery",
4  "n_plus": "n1",
5  "n_minus": "gnd",
6  "value": 10
7}

Current Source

A fixed current source. Current flows from n_minus to n_plus through the source.

1{
2  "type": "isource",
3  "name": "I1",
4  "n_plus": "n1",
5  "n_minus": "gnd",
6  "value": 0.01
7}

Capacitor

A capacitor between two nodes. Treated as an open circuit for DC analysis. For AC analysis, impedance = 1 / (jωC).

1{
2  "type": "capacitor",
3  "name": "C1",
4  "n1": "n1",
5  "n2": "gnd",
6  "value": 0.000001
7}

Inductor

An inductor between two nodes. Treated as a short circuit (wire) for DC analysis. For AC analysis, impedance = jωL.

1{
2  "type": "inductor",
3  "name": "L1",
4  "n1": "n1",
5  "n2": "n2",
6  "value": 0.001
7}

Op-Amp

An ideal op-amp. Enforces V(n_plus) = V(n_minus) and sources whatever current is needed at the output. Requires a feedback path in the circuit or the matrix will be singular.

1{
2  "type": "opamp",
3  "name": "U1",
4  "n_plus": "gnd",
5  "n_minus": "n2",
6  "n_out": "n_out"
7}

BJT Transistor (Small-Signal)

A BJT transistor using the small-signal model. This model is linearized around an operating point. It is best suited for AC small-signal analysis or DC analysis with a supply voltage present. Requires a collector supply voltage to produce physically meaningful results.

1{
2  "type": "bjt",
3  "name": "Q1",
4  "n_b": "n_b",
5  "n_c": "n_c",
6  "n_e": "n_e",
7  "gm": 0.04,
8  "rpi": 2500,
9  "ro": 100000
10}

Response

1{
2  "success": true,
3  "node_voltages": {
4    "n1": {"real": 10.0},
5    "n2": {"real": 5.0}
6  },
7  "branch_currents": {
8    "V_battery": {"real": -0.005}
9  }
10}

Node Voltages

Each non-ground node appears in node_voltages.

DC response:

1"n1": {"real": 10.0}

AC response:

1"n1": {
2  "magnitude": 0.707,
3  "phase_deg": -45.0,
4  "real": 0.5,
5  "imag": -0.5
6}

Branch Currents

Branch currents are returned for voltage sources, op-amps, and inductors, or components that add a branch current unknown to the simulation. The key is the component's name field (or auto-generated label if none was provided).

DC response:

1"V_battery": {"real": -0.005}

A negative value means current flows out of the positive terminal into the circuit, which is the standard convention.

Errors

Common causes of singular matrix

• A node is defined in nodes but no component connects it to anything
• An op-amp has no feedback resistor (the output is not connected back to the inverting input)
• A capacitor is the only path to ground for a node in DC analysis (capacitors are open circuits for DC)
• A BJT emitter node has no resistor connecting it to ground

Examples

Voltage divider (DC)

Two equal resistors splitting a 10V supply. Expects n1 = 10V, n2 = 5V.

1{
2  "nodes": ["gnd", "n1", "n2"],
3  "components": [
4    {"type": "vsource", "name": "V1", "n_plus": "n1", "n_minus": "gnd", "value": 10},
5    {"type": "resistor", "name": "R1", "n1": "n1", "n2": "n2", "value": 1000},
6    {"type": "resistor", "name": "R2", "n1": "n2", "n2": "gnd", "value": 1000}
7  ],
8  "analysis": {"type": "dc"}
9}

RC low-pass filter (AC)

At the cutoff frequency f = 1/(2πRC) ≈ 159Hz, the output magnitude should be ≈ 0.707 (-3dB) with a phase of -45°.

1{
2  "nodes": ["gnd", "n1", "n2"],
3  "components": [
4    {"type": "vsource", "name": "V_in", "n_plus": "n1", "n_minus": "gnd", "value": 1},
5    {"type": "resistor", "name": "R1", "n1": "n1", "n2": "n2", "value": 1000},
6    {"type": "capacitor", "name": "C1", "n1": "n2", "n2": "gnd", "value": 0.000001}
7  ],
8  "analysis": {"type": "ac", "frequency": 159.15}
9}

Inverting op-amp amplifier (DC)

Gain = -R2/R1 = -1. With V_in = 2V, expects n_out = -2V and n2 ≈ 0V (virtual ground).

1{
2  "nodes": ["gnd", "n1", "n2", "n_out"],
3  "components": [
4    {"type": "vsource", "name": "V_in", "n_plus": "n1", "n_minus": "gnd", "value": 2},
5    {"type": "resistor", "name": "R1", "n1": "n1", "n2": "n2", "value": 1000},
6    {"type": "resistor", "name": "R2", "n1": "n2", "n2": "n_out", "value": 1000},
7    {"type": "opamp", "name": "U1", "n_plus": "gnd", "n_minus": "n2", "n_out": "n_out"}
8  ],
9  "analysis": {"type": "dc"}
10}

BJT common-emitter amplifier (DC)

Gain ≈ -gm × Rc = -0.04 × 10000 = -400. With V_in = 0.01V, expects n_c ≈ 1V (pulled down 4V from Vcc=5V).

1{
2  "nodes": ["gnd", "n_b", "n_c", "n_e", "vcc"],
3  "components": [
4    {"type": "vsource", "name": "Vcc", "n_plus": "vcc", "n_minus": "gnd", "value": 5},
5    {"type": "vsource", "name": "V_in", "n_plus": "n_b", "n_minus": "gnd", "value": 0.01},
6    {"type": "resistor", "name": "Rc", "n1": "vcc", "n2": "n_c", "value": 10000},
7    {"type": "resistor", "name": "Re", "n1": "n_e", "n2": "gnd", "value": 100},
8    {"type": "bjt", "name": "Q1", "n_b": "n_b", "n_c": "n_c", "n_e": "n_e",
9     "gm": 0.04, "rpi": 2500, "ro": 100000}
10  ],
11  "analysis": {"type": "dc"}
12}

Notes

• Ground ("gnd") is always 0V and is excluded from the response. It is the reference point for all other voltages.
• Node names are case-sensitive. "N1" and "n1" are treated as different nodes.
• The BJT model is a linear small-signal approximation. It does not model saturation, cutoff, or thermal effects.
• The op-amp model is ideal: infinite gain, infinite input impedance, zero output impedance. It does not model slew rate, bandwidth limits, or supply rail clamping.
• For AC analysis, capacitors should not be the only path to ground for any node. They are open circuits at DC and will cause a singular matrix if no DC path exists.