============
Introduction
============

Why this environment exists
===========================

SLiCAP is a circuit-analysis program driven from Python.  Everything it can do
is available by writing instructions — and that is where the friction has
always been.  A designer who knows exactly which transfer to evaluate still has
to get the syntax right: the correct analysis function, a circuit object, a
transfer type with the source, detector and loop-gain reference it requires,
parameter substitution, stepping.  A misspelt detector or a transfer that does
not go with the chosen gain type costs an edit-run-read cycle every time.

The Structured Electronic Design Environment removes that burden.  It is a
graphical front end for **SLiCAP** (Symbolic Linear Circuit Analysis Program,
https://www.slicap.org) and **NGspice** in which you draw the circuit and
compose the instructions through dialogs.  The dialogs offer only what the
circuit in front of you actually has — its independent sources, its detectors,
its controlled sources, its parameters — and only the fields the chosen
analysis accepts.  An instruction is then correct by construction rather than
by proofreading.

What it does **not** do is design your circuit.  There is no automatic
topology, no optimiser, no hidden reasoning about your amplifier.  Design
remains yours; the environment removes the clerical work around it.

What it produces
================

The environment's product is an **instruction file**: a plain Python script at
the root of your project.

.. code-block:: python

   # file: instructions.py
   
   import SLiCAP as sl

   Vamp = sl.makeCircuit("sch/Vamp.slicap_sch")

   GG   = sl.doLaplace(Vamp, pardefs='circuit', numeric=True)
   LG   = sl.doLaplace(Vamp, transfer='loopgain', pardefs='circuit', numeric=True)
   PZ1  = sl.doPZ(Vamp, pardefs='circuit', numeric=True)

Nothing about that file is special: it is readable, editable by hand, and
version-controllable.  It has no side effects of its own, so a design script can
simply import it and use the results:

.. code-block:: python

   import instructions as instr

   f_c   = sl.findServoBandwidth(instr.LG.laplace)["hpf"]
   poles = instr.PZ1.poles

That is the point of the whole environment.  The dialogs are a convenience, the
script they write is the deliverable, and it puts the full symbolic and numeric
analysis of your circuit at your disposal: for design automation, for
verification, and for documentation that is generated rather than retyped.

How the pieces fit together
===========================

A **schematic** is the source of the netlist *and* the publication figure, 
so the circuit you analyse and the circuit in your report cannot drift apart.

From a schematic you create a **circuit object** — one explicit line in the
instruction file — and for that object you compose **instructions**.  Running
them produces **results**: symbolic expressions, poles and zeros, noise, time
responses, operating points.

Numeric results can be converted into **traces**, traces are placed on **axes**,
and axes are arranged into **figures**, each one statement in the same file.  
Results, tables and figures are then exported as **report snippets** — LaTeX, RST or HTML —
to be imported directly.  Nothing is copied by hand, so a changed component
value propagates from the drawing to ta published figure, a graph, a table, or 
an expression in one run.

Two analysis backends live in the same project.  **SLiCAP** answers the
symbolic, design-oriented questions: what does this transfer look like in terms
of the component values, where do the poles go, how much noise does this
topology cost.  **NGspice** answers the numeric, verification questions with
device models: does the biasing hold, what does the real transistor do.  The
same schematic types, the same project layout and the same instruction file
serve both.

What you can rely on
====================

* **Files are the truth.**  Schematics, netlists, libraries, instruction files
  and results are ordinary files in your project; the environment never becomes
  the only place your design lives.
* **Projects are self-contained.**  Everything a schematic references lives
  inside the project and is addressed relatively, so a project survives being
  moved, archived or handed over (see :doc:`/GUI/project/project`).
* **Nothing is rewritten behind your back.**  Editing is append-only: the
  dialogs add statements, and existing ones are left as they are for you to
  keep or delete.
* **The GUI is optional.**  Netlisting, export and every analysis are available
  from scripts and from the command line.  The environment makes the work
  easier; it never becomes a dependency of your design.
