Scripting Reference¶

This section describes the requirements for extending the Analysis framework.

General¶

User-made nodes live in the ~/.avis/nodes/ directory. You can create as many subdirectories at any depth. You should not have more than one script with the same filename in the same language, to avoid confusion.

Note

This section describes common properties amongst languages. Please refer to the actual languages for examples.

Format¶

AViS Accepts these basic data types. They can be either appear single or as an array.

Type	Bytes
short	2
int	4
double	8

These few things are parsed by the pre-processor. They are all optional except when stated.

Description

Comments at the top of the script, if any, will be parsed as the description of the node.
Input variables

Variables that will be parsed as the inputs for the node.
Output variables

Variables that will be parsed as the inputs for the node.
Progress variable

A variable which the script sets to display a progress bar on the node.
Entry point (not optional)

The function to be called when the node is executed. It must be a function with no arguments and no return value.

Marks are the single API requirement for an AViS script. Each mark is a comment starting with @ that immediately precedes its target, with no extra spaces or newlines in between. AViS does not, and will never require an include library / header, so your code will be entirely portable as the language allows it.

Example:

`@Some Mark`
This line of code is marked!

You are free to use any variable or function name as you like; the names are entirely local to your script. However, as the names will be shown on the node UI, names longer than 10 letters are not encouraged.

Tip

You can toggle the behavior of name rendering in the Preferences.

Arrays¶

Arrays in AViS is ordered as C-like: The right-est index advances the fastest. However, code in Fortran should write as normal: advancing the left-est index the fastest.

C++¶

The general format of a parse-able script is as follows.

Description:

//@Description
//@This text will appear on the top of the node
//@This is another line.

Input variables:
```
//@in
int numberOfFrames = 0;
```
Output variables:
```
//@out
int numberOfRedAtoms = 0;
```

Progress variable:

//@progress
double progressOfTheCode = 0;

Entry point:

//@entry
void DoSomething() {
   //do something fancy!
}

The code can be in global scope, or put into a class with the same name as the script. When the code is classed as such, multiple instances of the script can be used for the same graph, without sharing variables.

Arrays¶

C-like code uses raw-pointers as dynamic arrays, so you need to know the length of each dimension. They can be specified beside the in or out comment. Length variables can be either: an input or output variable, a variable declared as var, or a constant. All length variables must be of type int.

Example:

//@in cnt
short* takeAnArrayOfSizeCnt = 0;
//@out cnt 3
double* andReturnAnArrayOfSizeCntX3 = 0;

//@in
int birdCount = 0;
//@out numberOfBirds numberOfEggs
double* eggSizes = 0;
//@var
int numberOfEggs = 4;

For multi-dimensional arrays, the items are arranged row-major. That is, the right-est index advances the fastest.

Example:

//@in a b c
int* myArray = 0;

//The element at location [x][y][z] can be accessed as below.
//It is your responsibility to not overflow the indices!
int xyz = myArray[x*b*c + y*c + z];

Tip

If you want a “safe” way of handling pointers, you can use vectors:

//@in 100
double* array = 0;
std::vector<double> _array;

void SetArrays() {
   _array.resize(100);
   array = _array.data();
}

Tip

If you want to use other libraries that require additional compiler/linker flags, you can set them in Preferences. OpenMP flags are available.

Python¶

Note

As Python variable declarations are implicit, the type of the variable must be specified beside the #@in/#@out comment.

The general format of a parse-able script is as follows.

Description:

#@Description
#@This text will appear on the top of the node
#@This is another line.

Input variables:
```
#@in int
myVar = 0
```
Output variables:
```
#@out double
outVar = 0.0
```

Entry point:

#@entry
def DoSomething:
   #do something fancy!

Arrays¶

AViS uses the NumPy api for Python arrays. The type of variable is list(nt), where n = dim and t = first character of the element type.

Example:

using numpy as np

#@in list(1d)
myArray = np.zeros(5)

#@out list(2i)
myArray = np.zeros((100, 3), dtype=int32)

Fortran¶

Note

A fortran script should contain a primary module with the same name as the first module.

The general format of a parse-able script is as follows.

Description:

!@Description
!@This text will appear on the top of the node
!@This is another line.

Input variables:
```
!@in
INTEGER :: MYINT
```
Output variables:
```
!@out
REAL*8 :: DOUBLEVAR
```
Progress variable:
```
!@progress
REAL*8 :: PROGRESSMEOW
```

Entry point:

!@entry
SUBROUTINE HELLO()
   !say hello!
end subroutine HELLO

Arrays¶

To allow for interoperability with other languages, arrays must be declared as ALLOCATABLE TARGET s.

Example:

!@in
REAL*8, ALLOCATABLE, TARGET :: SOMEARRAY (:,:)