Read Me

================================================

 ENIAC - Electrical Network Interactive Console

 Andrea Viarengo andrea.viarengo(at)gmail.com

 Very Minimal Documentation

================================================

 It's still in an early stage of development, but some functions works.
 The interface is an interactive console which respond to commands (like unix shell or windows cmd)
 commands are interpreted by a lexical analyzer using a particular semantic algebra.
 
 More infos at http://eniac-lab.sourceforge.net/

0) Installation
=================

 Simply uncompress the zip/tar file.
 Double click on eniac.exe (Win) or eniac (on Linux/MacOSX)

 There are several example files into folder "examples", and working directory is set in this directory
 write

   menu

 from the prompt of eniac, and a simple menu will guide you through demostration files into directory "examples"  
 Otherwise You can execute them into Eniac with the command:

   read "filename"

 All these files are textual file, you can open them with any editor (like notepad.exe or vi)

 (if filename is written without extension, eniac search files .eniac or .txt) 
 Try the 'example.txt' file as first, you can execute it writing:

   read "example"  

 on Eniac console.

 Some default values are loaded on Eniac startup from "default.eniac" file

1) ENIAC perform some useful mathematical operation like:
==========================================================

   a) complex computation  
        a=(1+2*j)/(3+j)
        b=sin(4+5*j)
        c=1/inf

   b) polynomial computation
        p=(1+s)*(3+s)*(4+s)
        solve(p)
        integrate(p)

   c) polynomial ratios
        f=(s^2*4+s^5-8)/(s^3+s^2)
	g=(f+1)/f

   d) matrix computation
        M=matrix([1,2],[3,4])
        d=det(M)
   	I=ident(2)
	B=transpose(M)
	D=M*B^2		     
   	
 # write 'help' to get a minimal help on all defined functions or open the file example/library.txt
 # write 'globals' to get a list of all defined variables
 # write 'functions' to get list of all user-defined function

2) Eniac now have a full programming language
===========================================================

 Eniac use an internal virtual machine with about 43 basic instructions
 Execution is splitted into 2 phases:

  1) Compilation Eniac High level language -> VM low level code 
  2) Esecution of the VM code

 New flow control statements: 

  a) Conditional expression
       if a>6 and b<8 
         println "ok"
       else
         println "ko"

  b) Loops
       for i=0;i<10;i=i+1 
         println i 
       end

       i=0
       while i<10
         println i
       end

       i=0
       do 
         i=i+1
         println i
       until i<10

     It's possible use statement "break" and "continue" to exit fron loop or skip to next iteration.

  c) multiple cases:
       switch myvar
         case "first":   println "ok: 1"
                         break
         case "second":  println "ok: 2"
                         break;
       end

  d) function definition:

       function myfunc(a,b,c)
         d=a+b+c     # all of this are local
         e=global.k  # way to access global variable
         return d+k
       end

       k=33
       myfunc(1,2,3)  #return 39  

     All variables defined inside function are local.  global.<variable_name>  permit to access global variable.
    
 You can use debug statement:

 debug(0) debug disabled
 debug(1) run step by step eniac code
 debug(2) run step by step VM code

 To view how eniac code is compiled into VM code
 define a function with all your code and run

 vmcode "function-name"

 pay attention that "function-name" is a string so you have to use ""


3) ENIAC solve electrical LTI (Linear Time Invariant) networks.
=================================================================

 It's possible to use linear components:

 R ( [1,2] ,100        )  # resistor
 L ( [1,2] ,10         )  # inductor
 C ( [3,4] ,0.1p       )  # capacitor
 Av( [1,2] ,10 , [3,4] )  # Voltage Controlled (V[3,4]) Voltage Generator
 Gm( [1,2] ,10 , [3,4] )  # Voltage Controlled (V[3,4]) Current Generator
 Op( [1,3,4]           )  # Operation Amplifier 1=+ 2=- 4=out
 Tf( [1,2] ,10 , [3,4] )  # Transformer 

 node [0] is the ground (TODO: in future you could change the reference...)

 f=Gain([3],[2])  calculate transfer function V[3,0]/V[2,0]  
 g=Z([3,2])       calculate impedance beetween nodes 3 and 2

 bode(f)        draw bode plots of transfer function "f" on file "bode.gif".
 nyquist(f)     draw nyquist diagram on file "nyquist.gif"
 rootlocus(f)   draw root locus on file "roots.gif"

4) todos
=========

    a) time simulation and plot using FFT	
    b) write documentation!!
    c) construct try/catch/end
    d) plots also non-logarithmic
    e) several plots on the same file 
    		
5) Eniac Semantics
====================

 program:
   expr
   program;program
   if condition_or code_block
   if condition_or code_block else code_block
   for lvalue;condition_or;expr code_block 
   while condtion_or code_block
   do code_block until condition_or
   switch expr codeblock
   break
   continue
   case expr: program
   default:   program
   function name(varList) codeblock
   return expr
   assign varlist

 code_block:
   program end
   program else
   program until

 varlist:
   name         
   name,varlist 
   varlist=expr  --assign list to multiple var  i.e.: x,y,x=[1,2,3]  

 list_expr: 
   expr
   expr;list_expr

 expr:
   expr+term
   expr-term
   term

 term:
   term/factor
   term*factor
   factor

 factor:
   operand^operand
   operand

 operand:
   number
   -factor     
   (expr)
   unkvar       --for create polynomial 
   imagunit     --for create complex number
   lvalue       --store operations
   @lvalue      --indirect store operations
   [expr]       --list definition like [1,2,3,6+7,s^5]
   {datamap}    --hash map definition	like {first:33, second:77}

 lvalue:
   name         --recall var or call function without arguments	
   name.lvalue  --define structure
   lvalue=expr  --assign to var
   lvalue(list) --function call
   lvalue[list] --access list item 

 list:
   expr
   empty	       --permits empty items [1,2,,4] 		
   expr,list

 datamap:
   empty        --permits {}
   name:expr
   name:expr,datamap

 condition_or:
   condition_or or condition_and
   condition_and

 condition_and:
   condition_and and condition_factor
   condition_factor

 condition_factor:
   not condition_factor
   (condition_or)
   condition

 condition:
   expr <  expr
   expr <= expr
   expr == expr
   expr != expr
   expr >= expr
   expr >  expr