Troubleshooting & FAQ

Before sending a circuit to a simulator, GEEC runs a series of pre-flight checks automatically. These include verifying the internal structure of the request, confirming the selected analysis type is supported for the circuit (e.g., blocking symbolic analyses for non-linear components), and checking for logical inconsistencies such as duplicate component tags, design variable names that clash with reserved simulator symbols (Pi, f, s, t, ...), or duplicate user-result names. If any check fails, GEEC reports the error in the analysis dialog before the simulation starts - no server round-trip is made. This means many common mistakes are caught immediately, with a descriptive message pointing to the problem.

Common Issues & Solutions

Problem: Analysis fails with a validation error

Causes:

Floating components (not connected to anything)
Missing ground reference (0 V reference node)
No voltage or current source
Invalid component values

Solutions:

Check for floating components:
- Every component must have all terminals connected by wires
- Isolated components have no wires attached - connect or delete them
Add a ground reference:
- Every circuit needs at least one node at 0 V (ground)
- Add a Ground symbol from the Basic Components section of the left menu
- Connect it to the circuit's common return path (negative terminal of the source)
Verify circuit paths:
- Trace from the source's positive terminal through all components back to the negative terminal - the loop must be complete
- Check for floating wire ends that look connected but are not snapped to component terminals
Validate component values:
- Open the component's property dialog (right-click -> properties)
- Ensure the Value field is not empty
- Avoid physically impossible values (e.g., 1e100Ω)
- Design variable names (e.g., R, Cx) must have a numeric value set in Analysis / Settings / Design Variables

Problem: Analysis runs but no output appears

Causes:

Analysis dialog was closed
Output variable not configured
Analysis returned an error

Solutions:

Re-open the dialog:
- In the right panel, click the Analyses tab
- Click on the analysis name to re-open its dialog
Check for errors:
- The dialog shows a red error alert if the analysis failed
- Read the error message, then fix the circuit or parameters
- Use Help ? Log in the graph dialog menu bar to see the raw simulator output
Configure output variables (result analyses such as OP, AC):
- Open the analysis dialog and add a signal expression such as v(out) or i(R1) to the output field
- Named nodes are easier to reference - right-click a wire to rename it; enable Contact Names in the Tools tab to display names on the canvas
- See Expression Reference for signal syntax

Problem: Components not aligning to grid

Cause: The grid is toggled off, so snap is disabled.

Solution:

Press G to toggle the grid on
Adjust the grid step size in the bottom bar
Components snap to grid automatically when the grid is visible

Analysis Issues

Problem: "Convergence error" in NGSpice

Meaning: NGSpice's numerical solver cannot find a solution (usually for transient or non-linear circuits)

Common causes:

Poorly conditioned circuit (extreme component values)
Oscillating circuit causing solver difficulty
Stiff problem (vastly different time scales)

Solutions:

Add damping:
- Add a small resistor in series with inductors (e.g., 1m ?)
- Reduces numerical oscillations
Improve circuit conditioning:
- Avoid mixing very large and very small values (e.g., 1 pF and 1 F in the same circuit)
- Use physically realistic component values
Adjust the time step (transient analysis):
- Use a smaller time step for faster-changing signals
- Re-run with the adjusted parameters
Simplify the circuit:
- Remove unnecessary complexity temporarily
- Isolate which subsection causes the problem and test it alone
Check for inherent instability:
- Some circuits are oscillatory by design - the solver may legitimately struggle
- Use a pole-zero graph (NGSpice ? PZ graph) to check stability margins

Problem: Analysis runs but results look wrong

Diagnosis: Verify results make physical sense first.

Example: For a DC voltage divider (5 V source, 1 kΩ + 2 kΩ):

? Correct: v(out) = 3.33 V (5 V * 2k/(1k+2k))
? Wrong: 150 V (check source value and connections)
? Wrong: 0 V (check ground connection and node names)

If results seem wrong:

Inspect the netlist:
- Go to Export tab -> NetList section -> Spice
- Confirm component values and node connections match what you drew
Check output variable names:
- Node names are set by right-clicking a wire and renaming it
- Enable Contact Names in the Tools tab to display node names on the canvas
- Unnamed nodes receive auto-assigned numeric names from the simulator
Check output units:
- The simulator outputs SI base units (V, A, Hz) - axis labels in the graph confirm this
- Large impedance values (e.g., G? at low frequency) may be physically correct
Recheck component values:
- 1k = 1000Ω but 1 = 1Ω - the SI suffix matters
- Design variables: open Analysis -> Settings -> Design Variables to verify numeric values
- In expressions, write R*2 - curly braces are not used in GEEC ({R*2} is optional syntax)

Problem: Symbolic analysis fails or is greyed out

Causes:

Circuit contains non-linear components (diodes, transistors) - symbolic engines only support linear circuits
Circuit contains unsupported component types (e.g., Lossless Transmission Line for some analyses)

Solutions:

Use NGSpice analyses for circuits with non-linear components
Hover over a greyed-out analysis button - the tooltip explains why it is disabled

Problem: Simulations are very slow

Causes:

AC analysis with too many frequency points
Transient analysis with a very long time span or very small time step
Complex circuit with many nodes
Server under load

Solutions:

Reduce resolution for exploration:
- Fewer frequency points in AC (100 instead of 1000)
- Shorter transient window or larger time step
Use interactive sliders efficiently:
- Sliders re-run all open analyses on every move - close analysis dialogs you are not actively inspecting
Break up large circuits:
- Analyse subcircuits separately and verify each individually

File & Storage Issues

Problem: Project file won't load

Causes:

File is corrupted or an incomplete download
Very old file format

Solutions:

Try loading again - incomplete downloads can produce a truncated file; re-download or ask the sender to resend
Check the file extension - GEEC accepts .geec and legacy .json files; both can be opened with General -> File -> Load
If the file cannot be recovered - start a new project (General -> Project -> New circuit)
Prevent future loss - save frequently with General -> File -> Save; the undo history is in-memory only and is lost on page reload

Problem: Can't access server projects

Causes:

Not logged in or session has expired
Server is offline
Insufficient permissions (saving to server requires admin rights)

Solutions:

Check login status: Your name appears in the top-right of the top bar when logged in. Click the Login button on the right side of the top bar and enter your credentials (obtained from your teacher or administrator).
Reload the page to restore an expired session, then log in again.
Loading from the server is public - you do not need to be logged in to open circuits. If the Load from server dialog is empty, the server may be offline or contain no public circuits.
Saving to the server requires admin rights - regular users must use General -> File -> Save to download a .geec file instead.

Display & Interface Issues

Problem: Canvas is empty - components not visible

Cause: The circuit is outside the visible area, or the zoom level is extreme.

Solutions:

Scroll the mouse wheel (or use the zoom buttons in the bottom bar) to zoom out
Use the directional arrow widget in the bottom bar or Ctrl+Arrow keys to pan back to center

Problem: Keyboard shortcuts not working

Causes:

Browser focus is on a text field or another UI element, not the canvas
A browser extension is intercepting the shortcut

Solutions:

Click on an empty area of the canvas to give it focus, then retry the shortcut
Temporarily disable browser extensions
Use the top bar menus as a fallback
See Keyboard Shortcuts for the full reference

Problem: Interactive slider panel not visible

Cause: No sliders have been added to the circuit yet.

Solution:

Click Slider in the General tools section of the left menu to add one
The floating panel appears automatically once at least one slider exists
See Interactive Features for the full slider workflow

Export Issues

Problem: Exported image is blank or only partially shows the circuit

Solutions:

Zoom out so all components are visible on the canvas before exporting � the exporter captures the current canvas content
For a clean white-background image use JPEG (PNG is transparent)
For scalable, print-quality output use PDF (Export tab ? Vector image ? PDF)

Problem: PDF export looks different from canvas

Cause: The PDF renderer uses vector drawing at a fixed scale; text sizes and line weights may differ slightly from the canvas preview.

Solutions:

Open the exported PDF to verify it before submitting
Use the LaTeX export if you need precise scaling - see \gfig parameters in Results & Export

Numerical Precision Issues

Problem: Analysis shows 0 V everywhere

Likely cause: Extremely large or small component values causing numeric underflow or overflow

Solution:

Verify all component values are in a physically reasonable range
Use SI-prefix notation: 1k (1 kΩ), 10u (10 µF), 2m2 (2.2 mH)
Avoid exponents beyond roughly ~20 for component values

Problem: Extremely large numbers in results

This may be correct! Check the physics before concluding it is a bug.

Example: A 1 pF capacitor at 1 Hz has impedance $X_C = \frac{1}{2\pi f C} \approx 1.6 \times 10^{11}$ very large but physically correct value.

If the value is still unexpected, verify that the analysis frequency range and component values are appropriate for the circuit.

Non-linear Circuit Issues

Problem: NGSpice analysis fails for circuits with diodes or transistors

Causes:

Circuit biasing is incorrect (semiconductors need proper DC bias to operate)
Extreme switching or oscillation causing convergence failure

Solutions:

Check biasing:
- Verify the source voltage is sufficient to forward-bias the device
- Add appropriate bias resistors and supply rails
Simplify first:
- Replace semiconductors with ideal sources temporarily to verify the rest of the circuit
- Reintroduce components one at a time to isolate the problem
Convergence tips:
- Add a small series resistance to voltage sources (e.g., 1Ω) to help the solver
- Refer to the NGSpice convergence section above for more techniques

Frequently Asked Questions (FAQ)

General

Q: Is GEEC free? A: Yes, GEEC is developed at Czech Technical University and is freely available.

Q: What circuits can I analyse? A: Any linear circuit topology with passive components (R, L, C), sources, dependent sources, and two-port elements. NGSpice also handles non-linear elements (diodes, transistors). Complexity is limited by the server's computation time.

Q: Can I use GEEC offline? A: If you are running a local installation, yes. The hosted web version requires a network connection to the server for analysis. Contact your administrator about local deployment.

Q: How accurate are GEEC simulations? A: NGSpice results match standard SPICE accuracy. Symbolic analysis produces exact mathematical expressions - the result is as accurate as the underlying circuit model.

Q: Can GEEC print my circuit? A: Export as PDF (Export tab -> Vector image -> PDF) and print from your PDF viewer. There is no direct print button in GEEC.

Analysis Questions

Q: Should I use symbolic or numerical analysis? A: Use NGSpice for circuits with non-linear components, for time-domain simulation, or when you just need fast numeric results. Use symbolic when you want exact algebraic transfer functions - useful for understanding circuit behavior and deriving design equations. For linear circuits, both approaches give equivalent results.

Q: What is the difference between AC graph and AC numeric? A: AC graph sweeps frequency from start to stop and plots a Bode plot (magnitude + phase vs. frequency). AC numeric computes the AC response at a single frequency and returns a table of phasor values. For a Bode plot, use AC graph.

Q: What is a parametric sweep? A: A parametric sweep runs an analysis multiple times while stepping a component value or design variable through a range, producing a family of curves on one graph. Enable it with the Parameter checkbox inside any graph dialog. See Basic Analyses for syntax.

Q: Why is a symbolic analysis button greyed out? A: Hover over the button the tooltip explains the reason. Common causes: circuit contains non-linear components. Switch to an NGSpice analysis instead, or ask your administrator.

Q: Why does my pole-zero plot look unexpected? A: Pole-zero analysis assumes a linear small-signal model. For circuits with non-linear components the result is not meaningful. Also verify that the transfer function expression references the correct input/output nodes.

Q: Can I simulate power electronics (switching, PWM)? A: NGSpice supports transient analysis of switched circuits. Complex control loops and digital PWM generation are not specifically modelled. For advanced power electronics, a dedicated SPICE tool may be more appropriate.

Component Questions

Q: How do I use design variables (parametric component values)? A: Type a symbolic name (e.g., R or Cx) directly into the Value field of a component's property dialog. Then set numeric values via Analysis tab -> Settings sub-tab -> Design Variables. See Interactive Features for details.

Q: Where do I find component datasheets / models? A: Search the manufacturer's website. GEEC uses component models defined in the server component library; adding custom models requires administrator access.

Simulation Speed

Q: Why is simulation slow? A: NGSpice solves circuit equations numerically for every frequency or time point - speed scales with circuit size - number of points. Symbolic engines can be slow when simplifying complex algebraic expressions. Server load also affects response time.

Q: How can I speed things up? A: Reduce the number of frequency/time points for exploration, then increase resolution for the final result. Close analysis dialogs you are not actively using (they re-run on every slider move via F9 or automatically). Simplify the circuit to isolate the section you are studying.

Q: Where are my circuits saved? A: Circuits are saved as .geec files downloaded to your computer (General -> File -> Save). There is no automatic cloud save. Admin users can additionally save to the server database (General -> Server -> Save to server).

Q: How do I share a circuit with classmates? A: Export a .geec file (General -> File -> Save) and send it directly. If the circuit is saved on the server by an admin, share the project URL - the browser address bar updates to reflect the project ID after saving (e.g., https://geec.../42). There is no per-project access-control or sharing feature for regular users.

Q: How do I merge two edited copies of the same circuit? A: GEEC does not support automatic merging. Maintain one canonical version: one person edits, saves, and distributes the updated file.

Editing & Interface

Q: Can I import a circuit from LTspice? A: Not directly. You can export the LTspice netlist and use it as a reference to manually recreate the circuit in GEEC.

Q: Can I use GEEC on a tablet or phone? A: Basic touch is supported (tap to select, long-press for right-click equivalent, pinch to zoom). The full interface is designed for desktop/laptop; small screens make menus and dialog panels difficult to use.

Q: How do I recover deleted components? A: Press Undo (Ctrl+Z / Cmd+Z) immediately. The undo history is kept in-memory for the current session only and is lost when you reload the page. Save your work frequently.

Q: What is the best format for sharing a circuit diagram? A: PDF for printing and formal reports (vector, scales perfectly); PNG for quick digital sharing (transparent background); LaTeX (.tex + .pdf + gfig.sty) for embedding in a LaTeX document.

Q: What is the best format for sharing analysis results? A: PNG or SVG of the graph (graph dialog ? File ? Export PNG / Export SVG) for visual sharing. CSV (graph dialog -> File -> CSV) for raw data that others want to process in a spreadsheet - note the delimiter is always a semicolon.

Q: Can I embed GEEC circuits in Word or PowerPoint? A: Export as PNG or PDF and insert the image file into your document. .geec project files cannot be embedded in Office documents.

Advanced

Q: Can I write Python code to modify simulations? A: Advanced feature not covered in this manual. Possible for post-processing results. See advanced documentation.

Q: What are the limits of GEEC? A: Typically up to 1000 nodes, transient analysis up to seconds of simulated time (depending on computer). Some advanced power electronics features not supported.

Q: How do I report bugs? A: Check project GitHub or contact administrator. Include: circuit file, analysis type, error message, expected vs actual result.

Getting Help

Built-in Help

Press F1 in GEEC for overlay help
Hover over buttons for tooltips
Check Circuit tool helps find issues

Online Resources

GEEC Documentation - This manual
GEEC GitHub - Source code and issue tracker
Circuit Theory - Consult circuit analysis textbooks

Contacting Support

School/University: Contact your instructor or IT support
Work: Contact your IT department
Server Admin: Email server administrator for server-specific issues

Tips for Success

Start simple - Create basic circuits before complex ones
Save frequently - Ctrl+S regularly; backup important work
Verify results - Does output make physical sense?
Use grid - Press G to toggle grid; helps alignment
Label components - Makes netlists readable; easier to track
Backup work - Export projects; never lose work to disk failure
Learn shortcuts - See Keyboard Shortcuts; saves time
Check examples - If available, study example circuits
Test incrementally - Add components one at a time; test as you go
Document designs - Add text descriptions to circuits

Still stuck? Check earlier sections of this manual or contact support at your organization.