Index: trunk/doc/user/06_features/simulation/index.html
===================================================================
--- trunk/doc/user/06_features/simulation/index.html	(revision 8828)
+++ trunk/doc/user/06_features/simulation/index.html	(revision 8829)
@@ -126,3 +126,64 @@
 <H3 autotoc="yes"> Low level simulation </H3>
 <p>
 TODO
+
+
+<H3 autotoc="yes"> Test benching </H3>
+<p>
+The test bench mechanism is responsible for selecting parts of the circuit
+for simulation. Test benching operatos on project level. It is implemented
+using the test_bench project stance and
+<a href="../../../design/10_forge.html#des10.1">forge-if/test_bench attribute</a>
+in symbols and wirenets to conditionally omit objects that are not part of
+the currently selected test bench.
+
+<H4 autotoc="yes"> Test benching using the GUI </H3>
+<p>
+On the user interface, defining named test benches are done using the
+File menu, project submenu, project stances submenu; in the
+<i>project stances dialog</i> select the test_bench stance and click
+Edit... then enter a new test bench name; it is created and saved in
+the project config immediately.
+<p>
+Grouping object into test benches can be done on the GUI by selecting
+the given objects, then Select menu, Change selected objects submenu, Testbench
+affiliation submenu. This opens the <i>test bench quick edit</i> dialog which
+presents a matrix of checkboxes for all selected symbols vs. all
+project stances available at the time of opening the window. Ticking a checkbox
+means the given object is part of the given test bench.
+<p>
+After filling in the matrix for a few symbols, changing the test bench stance
+in the <i>project stances dialog</i> will expose the mechanism:
+<ul>
+	<li> if the test_bench stance is set to a named test bench, any symbol that
+	     has test bench affiliation but does not include the currently set test
+	     bench becomes <i>omitted</i>, which is indicated using a red cross;
+	     this is the case when a partial circuit is to be simulated; by default
+	     symbols not affiliated with any test benches are present included in
+	     all test benches
+	<li> if the test_bench stance is empty, the whole circuit is simulated
+</ul>
+
+<H4 autotoc="yes" id="test_bench"> Test benching in the config </H3>
+<p>
+The project stance test_bench is part of the config tree: /stances/test_bench
+is a string containign the name of the currently activated test bench; 
+/stances/test_bench_values is an array of all known test bench names. These
+shall be set on the project role (so they are part of the project file). The
+GUI expects and edits them on the project role.
+<p>
+Symbol test bench affiliation is controlled by the symbol attribute
+<a href="../../../design/10_forge.html#des10.1">forge-if/test_bench</a>.
+It could be an arbitrary forge script, but the GUI expects a script
+in the following structure:
+<pre>
+(stance.test_bench != "") && (stance.test_bench != "foo") && (stance.test_bench != "bar")
+scalar,omit
+sub,^.*$,yes,omit
+</pre>
+<p>
+For the GUI to understand, the expression in the first line must:
+<ul>
+	<li> start with <i>(stance.test_bench != "")<i>
+	<li> must list 1 or more <i>&& (stance.test_bench != "name")<i> sections with different test bench names
+</ul>