Quick Start

Documentation > QuickStart

Quick Start

In this basic quick start guide we will setup a virtual machine that sums two sinusoidal signals. First we need to create a virtual machine:

from vafmcircuits import Machine

machine = Machine(name='machine', dt=0.01)

The first line imports the main pyVAFM object, Machine, into the python console. The latter initialises a virtual machine with a timestep of 0.01, and stores it in a variable called machine. Having a reference to the machine is essential to make it execute instructions.

We now add a wave generator to the setup:

machine.AddCircuit(type='waver', name='osc', freq=1.2, amp=1)

The AddCircuit function tells machine to insert a new circuit of type waver in the scene. The newly created circuit will be called osc, which must be a unique identifier. The waver circuit exposes the freq and amp input channels that are used to control the shape of the generated signal. In this case, we are happy with constant frequency of 1.2 and amplitude of 1 (units are arbitrary), so we append their values to the initialisation arguments.

In the same way, we create the opAdd circuit:

machine.AddCircuit(type='opAdd', name='adder', factors=2)

The factors argument determines how many input signals can be connected to adder, to be summed out.

For the calculation to be performed, the input channels of adder must be connected to some signals. In this case we want to sum the two waves generated by osc:

machine.Connect('osc.sin','adder.in1')
machine.Connect('osc.cos','adder.in2')

These two instructions connect the output sin and cos of circuit osc to the inputs in1 and in2 of adder respectively. Now, when the waver circuit is updated, the sine and cosine values are fed to the opAdd, computing their sum.

If we want to be able to read adder's output, for example in a file, we need an output circuit to print it:

logger = machine.AddCircuit(type='output', name='logger', file='tutorial_basic.out', dump=1)
logger.Register('global.time','osc.sin','osc.cos','adder.out')

The first line creates the output circuit named logger, and instructs it to print every dump frames in the file 'tutorial_basic.out'. In this case it will print every frame. The second line tells logger which channels we want to print, through the Register function. Each channel is specified by a "circuitname.channelname" string. Although there is no circuit called global in our setup, no error will be returned upon execution. The global circuit identifier refers to the circuit container in the current context, in this case the main machine. The channel 'global.time' is always present in a virtual machine and contains the simulation time.

Finally we issue a Wait call:

machine.Wait(3)

The machine will integrate its circuits until 3 units of time are elapsed. Since the timestep was set to 0.01, the execution will perform 300 updates.

The full python input file is:

from vafmcircuits import Machine
 
machine = Machine(name='machine', dt=0.01)

machine.AddCircuit(type='waver', name='osc', freq=1.2, amp=1)

machine.AddCircuit(type='opAdd', name='adder', factors=2)

machine.Connect('osc.sin','adder.in1')
machine.Connect('osc.cos','adder.in2')

logger = machine.AddCircuit(type='output', name='logger', file='tutorial_basic.out', dump=1)
logger.Register('global.time','osc.sin','osc.cos','adder.out')

machine.Wait(3)

and the output is then plotted (gnuplot) as follows: