Circuit Simulator JavaScript Interface Documentation

This documentation outlines how to interact with the Circuit Simulator using JavaScript when it's embedded in an HTML page, particularly focusing on the use of an iframe to host the simulator.

Overview

To use the JavaScript interface, the simulator and the controlling JavaScript page must be served from the same origin (domain). This is required by the same-origin policy enforced by browsers for security reasons.

To run the simulator on your website, get the offline windows version, and put the contents of the circuitjs1/resources/app/war directory on your website.

You can run the CircuitJS1 simulation in an iframe. The CircuitJS1 object provides methods to interact with the simulator.

See a running example here.

Setup

<iframe id="circuitFrame" src="circuitjs.html?startCircuit=jsinterface.txt" width="800" height="550"></iframe>

...

<script>

var iframe = document.getElementById("circuitFrame");

// Wait for the circuit simulator to load
iframe.contentWindow.oncircuitjsloaded = function() {
    // Simulator is loaded, initialize your code here
    sim = iframe.contentWindow.CircuitJS1;

    // Set up callbacks for updates, analysis, and time steps (all optional)
    sim.onupdate = didUpdate;
    sim.ontimestep = didStep;
    sim.onanalyze = didAnalyze;
};

Available CircuitJS1 Methods

setSimRunning(boolean run)

• Description: Starts or stops the simulation.
• Parameters:
  • run (boolean): true to start the simulation, false to stop it.
• Example: CircuitJS1.setSimRunning(true);

getTime()

• Description: Retrieves the current simulation time.
• Returns: The simulation time in seconds as a number.
• Example: var time = CircuitJS1.getTime();

getTimeStep()

• Description: Gets the current time step of the simulation.
• Returns: The time step value.
• Example: var timeStep = CircuitJS1.getTimeStep();

setTimeStep(double ts) (Deprecated)

• Description: Sets the time step for the simulation. Note: This method is deprecated; changes to time step should be made using setMaxTimeStep.
• Parameters:
  • ts (double): The new time step to set.
• Example: CircuitJS1.setTimeStep(1e-6); // This is deprecated

getMaxTimeStep()

• Description: Returns the maximum time step allowed for the simulation.
• Returns: The maximum time step value.
• Example: var maxTimeStep = CircuitJS1.getMaxTimeStep();

setMaxTimeStep(double ts)

• Description: Sets a new maximum time step and also sets the current time step to this value.
• Parameters:
  • ts (double): The new maximum time step to set.
• Example: CircuitJS1.setMaxTimeStep(1e-3);

isRunning()

• Description: Checks if the simulation is currently running.
• Returns: true if the simulation is running, false otherwise.
• Example: if (CircuitJS1.isRunning()) { ... }

getNodeVoltage(String n)

• Description: Gets the voltage at a labeled node in the circuit.
• Parameters:
  • n (String): The name of the labeled node.
• Returns: The voltage at the node.
• Example: var nodeVoltage = CircuitJS1.getNodeVoltage("vsense");

setExtVoltage(String n, double v)

• Description: Sets the voltage of an external voltage element (see Inputs and Sources, Add External Voltage). These are different than labeled nodes, though they look the same. Labeled nodes are passive. Their voltage is determined by the rest of the circuit. External voltage elements are voltage sources. Their voltage is determined by javascript code.
• Parameters:
  • n (String): The name of the external voltage element to set the voltage for.
  • v (double): The voltage value to set.
• Example: CircuitJS1.setExtVoltage("extsin", 5);

getElements()

• Description: Retrieves all elements currently in the circuit.
• Returns: An array of circuit elements. See below for methods supported on these element objects.
• Example: var elements = CircuitJS1.getElements();

getCircuitAsSVG()

• Description: Exports the current circuit as an SVG string.
• Returns: The SVG representation of the circuit.
• Example: var svgData = CircuitJS1.getCircuitAsSVG();

exportCircuit()

• Description: Exports the current circuit to a string format for saving or transmission.
• Returns: A string representation of the circuit.
• Example: var circuitExport = CircuitJS1.exportCircuit();

importCircuit(String circuit, boolean subcircuitsOnly)

• Description: Imports a circuit from a string, potentially only loading subcircuits.
• Parameters:
  • circuit (String): The string representation of the circuit to import (as returned by exportCircuit()).
  • subcircuitsOnly (boolean): If true, only subcircuits are imported.
• Example: CircuitJS1.importCircuit(circuitString, false);

Circuit Element Methods

getType()

• Description: Retrieves the type of the circuit element.
• Returns: A string representing the class name of the element.
• Example: var elementType = element.getType();

getInfo()

• Description: Gets information about the circuit element, which might include voltage, current, or other relevant data points.
• Returns: An array or object containing information about the element.
• Example: var elementInfo = element.getInfo();

getVoltageDiff()

• Description: Returns the voltage difference across the element. This is particularly useful for two-terminal elements like resistors.
• Returns: The voltage difference as a number.
• Example: var voltageDiff = element.getVoltageDiff();

getVoltage(n)

• Description: Gets the voltage at a specific node (or post) of the element.
• Parameters:
  • n (number): The index of the node to check.
• Returns: The voltage at the specified node.
• Example: var nodeVoltage = element.getVoltage(0);

getCurrent()

• Description: Retrieves the current flowing through the element.
• Returns: The current as a number.
• Example: var current = element.getCurrent();

getLabelName() (For LabeledNodeElm)

• Description: Returns the name of the label for elements that are labeled nodes.
• Returns: The label name as a string.
• Example: var labelName = labelElm.getLabelName();

getPostCount()

• Description: Returns the number of posts (connection points) for the element.
• Returns: The post count as a number.
• Example: var postCount = element.getPostCount();

Callbacks

• onupdate: Called when the simulator updates its display (usually 60 times per second).

  sim.onupdate = didUpdate;
  ...
  function didUpdate(sim) {
      // Update UI with simulation data
  }

• ontimestep: Called every time step of the simulation.

  sim.ontimestep = didStep;
  ...
  function didStep(sim) {
      // Perform actions per time step
  }

• onanalyze: Called when the circuit is analyzed (loaded or edited).

  sim.onanalyze = didAnalyze;
  ...
  function didAnalyze(sim) {
      // React to changes in circuit
  }