ARgorithmToolkit 0.0.7

A utility toolkit to help develop algorithms suitable for ARgorithm

ARgorithm

Work in Progress

The ARgorithm project provides an interface to render your algorithms and data structures in augmented reality. The ARgorithmToolkit package offers packages and a command line interface needed to make and submit algorithms for the following.

How does it work ?

The Toolkit package is for developers who want to transport their own algorithms into augmented reality. The toolkit provides you with a template library which works just like your usual template library except this one records states . Each state is an event that occurs in your data structure and by keeping track of the states of your variables , data structures etc we then render them in augmented reality.

Getting started

You can install the ARgorithmToolkit using pip

pip install ARgorithmToolkit

or you can clone the repo

git clone https://github.com/ARgorithm/Toolkit.git 
cd Toolkit
make init

After that you can get started with your own ARgorithm

python -m ARgorithmToolkit init

This will generate your .py file and your .config.json file.

1. The <name>.py file will store your code that you will submit to the server hosting all ARgorithms
2. The <name>.config.json stores important details about your ARgorithm such as its purpose and parameters required

The <name>.py file initially looks like this

import ARgorithmToolkit

def run(**kwargs):
    stateset = ARgorithmToolkit.StateSet()

    #
    #	Your code
	#

    return

You can add whatever code you want to this file using all the tools and classes present in ARgorithmToolkit but be sure to

1. Your file should have one function which takes **kwargs input (refer here to know more about kwargs) that will should perform whatever you desire and should return the stateset. You can check out later in the document on how to use this stateset
2. you can create classes and additional functions in your code. Support for importing external modules is not yet added so its advisable not to add those.

the <name>.config.json file is a JSON file storing all the metadata

{
    "argorithmID" : "<name>",
    "file" : "<name>.py",
    "function" : "<function to be called>",
    "parameters" : {
        "variable-name" : "<data-type>"
    } , 
    "default" : {
        "variable-name" : "<value>"
    },
    "description" : "Tell us about your ARgorithm"
}

Key	Description
argorithmID	name of your ARgorithm , this is generally pre filled from when you run the init command. The name of your code file should be name.py and the config should be name.config.json. [will be fixed later]
file	The file containing your codefile
function	The function that is going to be called
parameters	the parameters that your ARgorithm would need, this helps in anyone using your ARgorithm to understand what is the input format
default	default parameters in case no parameters are passed
description	The description of ARgorithm. Helpful to people using your ARgorithm as well as other developers

You can check out ARgorithm examples in our Github Repo

Once you are done , you can submit to server by running

python -m ARgorithmToolkit submit

or

python -m ARgorithmToolkit submit --name <name>

you can test your ARgorithm submission by using

python -m ARgorithmToolkit test

you can delete your ARgorithm submission by using

python -m ARgorithmToolkit delete

if running server image on local machine , add -l or --local flag in the submit,delete and test commands . To run the server locally , pull the docker image alanjohn/argorithm-server:latest and run it. Check out server repo here

Using ARgorithmToolkit

ARgorithmToolkit adds a few extra steps when it comes to initializing instances whose states you want to record but thats because a lot of data has to be maintained in order for smooth transitions

>>> import ARgorithmToolkit
>>> algo = ARgorithmToolkit.StateSet()
>>> x = ARgorithmToolkit.Variable('x',algo,0,comments='Our first variable')
>>> x.value
0
>>> x.value += 10
>>> x.value
10
>>> print(algo)
{'state_type': 'variable_declare', 'state_def': {'variable_name': 'x', 'value': 0}, 'comments': 'Our first variable'}
{'state_type': 'variable_highlight', 'state_def': {'variable_name': 'x', 'value': 10}, 'comments': ''}

As ARgorithm is tool for creating visual demonstration , you can add comments parameter to most functions. These comments get included in states and get featured as text when that state is rendered in AR.

Make sure you make the objects you want to keep track of as part of the same stateset. Each object is instantiated with a name this is important to identify arrays when rendering them

You can refer the docs and samples in the repo to understand more clearly.

Priority Queue

ARgorithmToolkit.PriorityQueue

>>> import ARgorithmToolkit
>>> algo = ARgorithmToolkit.StateSet()
>>> pq = ARgorithmToolkit.PriorityQueue('pq',algo,comments="declaring priority queue")
>>> pq.offer(9)
>>> pq.offer(3)
>>> pq.offer(7)
>>> len(pq)
3
>>> pq.peek("peeking the queue")
3
>>> pq.poll()
3
>>> len(pq)
2
>>> pq.peek()
7
>>> pq.empty()
False

Methods Supported

Method	Parameters	Description	example
Peek		returns first element of priority queue	pq.peek()
Poll		pops and returns first element of priority queue	pq.poll()
Offer	element : any	add element to priority queue	pq.offer(elem)
Empty		returns boolean indicating whether queue is empty or not	pq.empty()

vectors

ARgorithmToolkit.vector

>>> import ARgorithmToolkit
>>> algo = ARgorithmToolkit.StateSet()
>>> vector = ARgorithmToolkit.Vector('arr' , algo)
>>> print(vector)
[]
>>> vector.insert(12)
>>> vector.insert(11,0,comments="lets insert a number at index 0")
>> vector[0]
11
>>> for x in vector:
...     print(x)
... 
11
12
>>> print(algo)
{'state_type': 'vector_declare', 'state_def': {'variable_name': 'arr', 'body': [12]}, 'comments': ''}
{'state_type': 'vector_insert', 'state_def': {'variable_name': 'arr', 'body': [12], 'element': 12, 'index': 1}, 'comments': ''}
{'state_type': 'vector_insert', 'state_def': {'variable_name': 'arr', 'body': [11, 12], 'element': 11, 'index': 0}, 'comments': 'lets insert a number at index 0'}
{'state_type': 'vector_iter', 'state_def': {'variable_name': 'arr', 'body': [11, 12], 'index': 0}, 'comments': ''}
{'state_type': 'vector_iter', 'state_def': {'variable_name': 'arr', 'body': [11, 12], 'index': 0}, 'comments': ''}
{'state_type': 'vector_iter', 'state_def': {'variable_name': 'arr', 'body': [11, 12], 'index': 1}, 'comments': ''}

Methods supported :

Method	Parameters	Description	example
indexing	index : int	accessing a certain index of vector	arr[0]
slicing	slice:slice	accessing a sub vector of vector	arr[1:4]
insert	value:any index:int (optional)	inserting a element at an index or if no index specified default last	arr.insert(10) ; arr.insert(10,2)
remove	value:any (optional) index:int(optional)	removing a particular value or from a particular index. Specify only one of the two	arr.remove(value=10) arr.remove(index=8)
compare	index1 : int index2 : int func : function (optional)	compares the values at the two indexes. returns result of == if func not specified	arr.compare(1,2)
swap	index1 : int index2 : int	swaps the values at the two indexes	arr.swap(2,3)

Queue

ARgorithmToolkit.Queue

>>> import ARgorithmToolkit
>>> algo = ARgorithmToolkit.StateSet()
>>> queue = ARgorithmToolkit.Queue('qu',algo)
>>> queue.push(1)
>>> queue.push(2)
>>> queue.front()
1
>>> queue.pop()
1
>>> len(queue)
1
>>> while not queue.empty():
...     queue.pop()
... 
2
>>> print(algo)
{'state_type': 'queue_declare', 'state_def': {'variable_name': 'qu', 'body': []}, 'comments': ''}
{'state_type': 'queue_push', 'state_def': {'variable_name': 'qu', 'body': [1], 'element': 1}, 'comments': ''}
{'state_type': 'queue_push', 'state_def': {'variable_name': 'qu', 'body': [1, 2], 'element': 2}, 'comments': ''}
{'state_type': 'queue_front', 'state_def': {'variable_name': 'qu', 'body': [1, 2]}, 'comments': ''}
{'state_type': 'queue_pop', 'state_def': {'variable_name': 'qu', 'body': [2]}, 'comments': ''}
{'state_type': 'queue_pop', 'state_def': {'variable_name': 'qu', 'body': []}, 'comments': ''}

Methods supported

method	parameter	description	example
push	value:int	pushes to back of queue	q.push(1)
pop		pops from front of queue	q.pop()
front		displays the front of queue	q.front()
back		displays the back of queue	q.back()
empty		boolean value that indicates whether queue is empty	q.empty()

Stack

ARgorithmToolkit.Stack

>>> import ARgorithmToolkit
>>> algo = ARgorithmToolkit.StateSet()
>>> stack = ARgorithmToolkit.Stack('st',algo)
>>> stack.push(1)
>>> stack.push(2)
>>> stack.top()
2
>>> stack.pop()
2
>>> len(stack)
1
>>> while not stack.empty():
...     stack.pop()
... 
1
>>> print(algo)
{'state_type': 'stack_declare', 'state_def': {'variable_name': 'st', 'body': []}, 'comments': ''}
{'state_type': 'stack_push', 'state_def': {'variable_name': 'st', 'body': [1], 'element': 1}, 'comments': ''}
{'state_type': 'stack_push', 'state_def': {'variable_name': 'st', 'body': [1, 2], 'element': 2}, 'comments': ''}
{'state_type': 'stack_top', 'state_def': {'variable_name': 'st', 'body': [1, 2]}, 'comments': ''}
{'state_type': 'stack_pop', 'state_def': {'variable_name': 'st', 'body': [1]}, 'comments': ''}
{'state_type': 'stack_pop', 'state_def': {'variable_name': 'st', 'body': []}, 'comments': ''}

Methods supported

method	parameter	description	example
push	value:int	pushes to top of stack	q.push(1)
pop		pops from top of stack	q.pop()
top		displays the top of stack	q.top()
empty		boolean value that indicates whether stack is empty	q.empty()