====== Actsim: an ACT simulator ======

To run ''actsim'', you need to select the ACT file to simulate and the top-level process for your design:

<code>
% actsim file.act process
actsim>
</code>

===== A simple example =====

The following ACT file is a CHP example that sends three integers on an output channel, and connects that process to one that simply receives an integer and displays it to the screen.

<file act simple.act>

defproc my_source (chan!(int) X)
{
   chp {
      X!0; X!4; X!3 
   }
}

defproc my_sink (chan?(int) X)
{
   int x;
   chp {
      *[ X?x; log ("received ", x) ]
   }
}   

defproc test()
{
    my_source s;
    my_sink t(s.X);
}
</file>

A simple simulation can be run as follows:

<code>
% actsim simple.act test
WARNING: my_sink<>: substituting chp model (requested prs, not found)
WARNING: my_source<>: substituting chp model (requested prs, not found)
actsim> cycle
[                  10] <t>  received 0
[                  20] <t>  received 4
[                  30] <t>  received 3
actsim> quit
</code>

''actsim'' was started by specifying the ''simple.act'' file as the design input, and ''test'' as the top-level process for the simulation. When ''actsim'' started, two warnings were displayed that say that ''actsim'' was looking for ''prs'' models for the circuit, but found a ''chp'' model instead which it substituted. ACT can specify circuits at different levels of abstraction using [[language:langs:start|sub-languages]], and the simulator has to select one of them. This warning can be turned off using one of the standard ACT [[stdoptions:start|command-line options]] as follows:

<code>
% actsim -Wlang_subst:off simple.act test
actsim> cycle
[                  10] <t>  received 0
[                  20] <t>  received 4
[                  30] <t>  received 3
actsim> quit
</code>

The ''cycle'' command will run the simulation until there is nothing left to simulate. The ''log'' command is used to display output messages; when the circuit is implemented, all ''log'' commands in CHP are replaced by ''skip''.  The message displayed has three parts:
   * The first part is the current simulation time displayed in square brackets. By default, every event takes ten time units. (This can be modified by specifying delay parameters in a configuration file.)
   * The next part is the name of the instance, in angle brackets. Here the log message was generated by ''my_sink'' instance ''t''.
   * The final part is the actual text from the log command

===== Commands =====
==== General ====

<code>help</code>
display a list of commands with short descriptions

<code>exit</code>
terminate

<code>source <file></code>
read in a script file and execute the commands within


==== Timing ====

<code>random [<min> <max>]</code>
Set the random timing mode and optionally specify the default random timing bounds for all nodes.

<code>random_seed <seed></code>
set the seed for the random timing mode.

<code>norandom</code>
Set the deterministic timing mode.

<code>random_choice on|off</code>
turn on/off random exclhi/lo firings



==== Running Simulation ====

<code>mode reset|run</code>
set current running mode.
^ Mode ^ Effect ^
| ''reset'' | ''reset'' turns off weak interference warnings (node still becomes X). During chip initialization, there can be weak interference since the simulator assumes all nodes are initially X. Setting the mode to ''reset'' during the reset phase prevents these warnings from being printed to the screen. |
| ''run'' | Warnings of weak interference are enabled. This should be the standard mode after the reset phase has completed. |


<code>initialize <proc></code>
initialize the simulation with the specified process as the top-level.

<code>step [<steps>]</code>
simulate <steps> events (default is 1)

<code>advance [<duration>]</code>
simulate for <duration> units of simulation time (default is 1)

<code>cycle</code>
simulate until there is nothing more to simulate.

<code>break <variable>
breakpt <variable>
</code>

set a breakpoint on <variable>.

<code>break-on-warn</code>
toggles the break-on-warn flag which stops/doesn't stop simulation on instability or interference

<code>exit-on-warn</code>
like break-on-warn, but exits prsim


==== Setting/Getting  Values ====

<code>set <variable> <value></code>
set <variable> to specified <value>

<code>get <variable> [#f]</code>
get value of <variable>. This returns the value in addition to displaying it. If the optional argument is provided and set to ''#f'', then the value is returned without displaying it to the screen.

<code>watch <n1> <n2> ...</code>
add watchpoints for <n1>, <n2>, etc.

<code>unwatch <n1> <n2> ...</code>
delete watchpoints for <n1>, <n2>, etc.

<code>timescale <ps></code>
Set the conversion from integer time units to picoseconds for simulation tracing. By default the conversion is 10ps, but this default can be changed by updating the simulation configuration file.

<code>vcd_start <flle></code>
Create a VCD file that contains all the variables that are currently watched. The timescale is used for the time reported in the VCD output.

<code>vcd_stop</code>
Stop VCD file generation.



==== Debug ====

<code>status 0|1|X</code>
list all nodes with specified value

<code>break-on-warn</code>
Stop the simulation when a warning is generated

<code>exit-on-warn</code>
Quit simulation on a warning

<code>resume-on-warn</code>
Don't stop/exit simulation when a warning is generated

(Work in progress; try running ''help'' on the command-line)

==== User-defined commands ====

There is a complete programming language on the command-line. The language is a subset of the Scheme programming language. The implemented subset is documented on [[https://github.com/asyncvlsi/act/tree/master/miniscm#readme|github]].

Everything typed on the command-line is executed by adding a set of parentheses around it. Hence, a command like
''set x 1'' typed on the command-line or in a standard script is actually executed as ''(set x 1)''.  A script can be written directly in  the Scheme subset and loaded using ''load-scm "file.scm"'' on the command-line.

This means your Scheme programs can execute any of the standard ''actsim'' commands, as they are built-in to the Scheme execution engine. For example, if you want to see the output of a gate for all possible input settings, here's a Scheme function you could define:
<code scheme>
(define try-all (lambda (inlist out)
   (begin
      (if (null? inlist)  (begin (cycle) (get out))
          (begin
                (echo "-- " (car inlist) " <- 0")
                (set (car inlist) 0)
                (cycle)
                (try-all (cdr inlist) out)
                (echo "-- " (car inlist) " <- 1")
                (set (car inlist) 1)
                (cycle)
                (try-all (cdr inlist) out)
          )
      )
    )
  )
)
</code>
If you load this definition, then 
<code>
(actsim) try-all (list "a" "b" "c") "out"
</code>
will try all possible 0/1 assignments to ''a'', ''b'', and ''c'', and display the value of ''out''.

===== Example with a test environment =====

To illustrate how one can write a range of test benches for ''actsim'', we use a simple example of an adder (in ''adder.act'') written as follows:

<file act adder.act>
defproc adder(chan?(int) A, B; chan!(int) C)
{
    int a, b;
    chp {
        *[ A?a, B?b; C!(a+b) ]
    }
}
</file>

==== Direct environment in ACT ====

A simple test environment would look like this:

<file act testadd.act>
import "adder.act";

defproc src1 (chan!(int) X)
{
   chp {
      X!3; X!5; X!2  // test inputs
    }
}

defproc src2(chan!(int) X)
{
   chp {
      X!7; X!9; X!3
   }
}

defproc sink(chan?(int) X)
{ 
   int x;
   chp {
      *[ X?x; log ("received ", x) ]   // read a value and display it
   }
}

defproc test()
{
    adder a;
    src1 s1(a.A);
    src2 s2(a.B);
    sink sx(a.C);
 }
</file>
Running ''actsim testadd.act test'' will start the simulation with the defined environment. 

Since this is a commonly-used approach, the [[stdlib:start|ACT standard library]] contains a [[sim:start|''sim'']] (for simulation) namespace that has commonly used sources and sinks. 

==== Using pre-defined sources and sinks with data in the ACT file ====

The same example can be written using the helper processes provided as follows:

<file act testadd2.act>
import "adder.act";
import sim; // import simulation namespace

defproc test()
{
    adder a;
    sim::source_seq<32, // 32-bit data
                    false, // don't repeat the sequence of values
                    3, // three data values
                    {3,5,2}  // the data values
                    > s1(a.A);
    sim::source_seq<32, false, 3, {7,9,3}> s2(a.B);
    sim::sink<true, // log output
              32  // 32-bit
              > sx(a.C);
 }
</file>

==== Using files for test data ====

Instead of providing the data values in the ACT test environment, you can instead have data values read in from a file. ''sim::file_source'' can be used for this purpose as follows:

<file act testadd3.act>
import "adder.act";
import sim; // import simulation namespace

defproc test()
{
    adder a;
    // The first parameter is the file ID (default name is _infile_.0). 
    // The second parameter is whether the file should be looped.
    // The third parameter is the bit-width.
    sim::file_source<0, false, 32> s1(a.A);
    
    // This could also use a file source
    sim::source_seq<32, false, 3, {7,9,3}> s2(a.B);
    sim::sink<true, // log output
              32  // 32-bit
              > sx(a.C);
 }
</file>

This example will also need a file ''_infile_.0'' that contains the [[sim:start|list of values]].
===== Mixed-signal simulations =====

Mixed analog-digital simulations can be done in ''actsim'', if it was built with Xyce (see [[https://github.com/rmanohar/actsim#building-with-xyce|building actsim with Xyce]]). 
There are two ways to specify an analog simulation: 
   * Specify prs for a process and simulate it at the device level using spice models. This can be done by specifying the device level using an ACT [[config:runtime#circuit_level_selection|configuration file]] that is loaded at runtime into ''actsim''. The simulator will use the same approach as [[tools:netgen|prs2net]] to generate the SPICE netlist for the specified processes/instances.
   * Specify a blackbox process with ports and provide a netlist file to simulate. This provides more flexibility in the netlist simulated by Xyce; for example it can include extracted parasitics.

The method to specify a blackbox process is described [[https://avlsi.csl.yale.edu/act/doku.php?id=config:runtime#external_black_box_support|here]]. An example with three inverters, one each with digital actsim simulation, analog simulation of prs and analog simulation of blackbox spice netlist can be found at [[https://github.com/ThomasJagielski/Analog-ACT-Example|this repository]].


===== Configuration file =====

An ACT configuration file can be read into ''actsim'' to control its behavior. The following summarizes configuration options that affect the behavior of the simulator (beyond the default ACT configurations that affect all tools). The simulator loads in the default ''actsim.conf'' file, but any of those parameters can be augmented/over-ridden using the ''-cnf'' [[stdoptions:start|command-line option]].


==== CHP configuration options ====

<code>
begin sim
  begin chp
    int inf_loop_opt 0
  end
end
</code>
''actsim'' can detect an infinite loop where no state changes occur, and delete the process from the simulation environment if this flag is turned on (by being set to 1).

<code>
begin sim
  begin chp
    int default_delay 0
    real default_leakage 0
    int default_area 0
  end
end
</code>
These set default simulation parameters for CHP processes. The default delay sets the value for each non-skip basic statement (send, receive, assignment) in a CHP program. The default leakage per process can be secified (in nW), as can the default area (in square microns).

<code>
begin sim
  begin chp
    int debug_metrics 0
  end
end
</code>
If this is set to 1, then debugging messages are printed out showing the metrics that ''actsim'' was looking for in the configuration file, and what metrics were in fact found.

==== Mixed-signal simulation ====

The mixed-signal simulation parameters are used to configure the interface to Xyce, and are contained in a sim.device block.
<code>
begin sim
  begin device
    # put mixed-signal parameters here  
  end
end
</code>
The parameters are
<code>
real timescale 1e-12  
</code>
This is used for the time resolution of the Xyce output trace files, if any.

<code>
real analog_window 0.05
</code>
This specifies when an analog signal output should be treated as a digital 0 or digital 1.  The value 0.05 means within 5% of the rail-to-rail voltage. So for a 1V power supply, this would be 0.95 for a digital 1 threshold, and 0.05 for a digital 0 threshold.

<code>
int case_for_sim 1
</code>
SPICE is case-insensitive, and the internals of the analog simulator usually have either a lowercase or uppercase name for all the signals. Set this to 1 (the default, and correct value for Xyce) if it is uppercase, 0 for lowercase.

<code>
real settling_time 1e-12
</code>
This is the settling time parameter for the built-in ADC device used to convert between the digital and analog signals.

<code>
int dump_all 1
</code>
If this is true, all voltage signals should be saved to the output trace file. Otherwise, only the interface signals are saved to the trace file.

<code>
string output_format "prn:lxt2:alint:vcd"
</code>
This specifies which output trace file formats should be generated from the underlying analog simulation engine. Any number of colon-separated formats are supported, but only one of the built-in formats (raw, prn, etc) can be used.

<code>
int waveform_steps 10
real waveform_time 10e-12
</code>
The digital input is converted to a ramp before being fed to the analog simulation. This specifies the duration and number of steps used for the conversion.

<code>
string model_files "path.sp"
</code>
By default, the simulation will look for the file ''models.sp'' in the ACT configuration directory. This string can be used to override this default and pick a different SPICE file that includes all the needed models.

<code>
string outfile "xyce_out"
</code>
This is the name of the trace file output that is generated.

<code>
real stop_time 100e-12
</code>
This is the time at which the trace file output should stop.

==== Standard sim namespace helper functions ====

The standard simulation library (in the sim namespace) uses a few configuration file settings to pick the names
of the files for I/O. 

<code>
begin sim
  begin file
    string prefix "_infile_"
  end
end
</code>
Change this parameter to modify the default file names used by the file I/O library used by the standard simulation namespace.

Alternatively, a file name table can be specified whose entries are the names of the files to be used for each file ID (0 = first entry, 1 = second entry, etc.)
<code>
begin sim
  begin file
    string_table name_table "file1.in" "file2.in"
  end
end
</code>
If this parameter is specified, then the prefix parameter is ignored.