# NNDy

## INTRO
This is the user guide for NNDy
The code is thoroughly commented so this guide will focus on the configuration, installation of packages and general usage of the optimization package as it was implemented by me

For some info about the algorithm and the architecture refer to the notebook 
01/28 - NN-Dy explanatory intro
of the lab's OneNote under People's NOtes/Fabio


The original and bare code can be found in this git
Versions of the script already adapted and ready to use for different sequences of the experiment are instead to be found in the main lab git, in a dedicated folder within the labscript sequences folder

If you're using the package on the main control pc or in the main preplab pc, there's no need for setup
Skip to COST FUNCTION section

## MLOOP installation
Install M-LOOP package from pip in the same python environment where you installed labscript

pip install M-LOOP

See here
https://m-loop.readthedocs.io/en/stable/install.html#installing-with-pip

Check dependencies if needed

## TENSORFLOW INSTALLATION FOR GPU (not for windows :( )
If you want the NN to be built and run with your GPU you need to make sure that the tensorflow version installed leverages cuda and your GPU (if you install the tensorflow package from pip or via M-LOOP dependencies this is not usually the case)

Follow here
https://www.tensorflow.org/install/pip

## DOWNLOAD CODE FROM THIS GIT
Into the sequences folder of your local labscript installation create a dedicated folder for NNDy where you copy:
<ul>
	<li>NNDy.py</li>
	<li>NNDy_Interface.py</li>
	<li>runmanager_remote.py</li>	
    <li>experiment_remote.py - not necessary, used only for testing and debugging</li>
	<li>DA/newRun_NNDy.py</li>
</ul>

## RUNMANAGER_REMOTE.PY
Modify the path where it will look for the sequences, this will be the shared_drive path of the specified in the during configuration of the labscript software (see https://labscriptsuite.org/en/latest/setup/configuration/ for more details)


## COST FUNCTION
In the first lines of NNDy.py you can indicate the file that will perform the analysis of the shot(s) at each iteration


How should this file be written? - see /DA/TestDA.py for more instructions
The essential part of the file is the function 

def cost(hdf_file):

This is the function that will be transferred to the internal structure of the interface (see NNDy_Interface.py) and be called after the experiment sequence is finished

The function reads the hdf_file of the shot and returns a dictionary with 
<ul>
	<li>cost</li>
	<li>bad flag</li>
	<li>uncertainity</li>
</ul>

Within this cost function the analysis routine is initiated and handled to return the desired observable from which you want to estimate the cost
The analysis can be customized in any way you desire, as long as it relies of the hdf file to read the results of the shot and the cost function returns the dictionary as explained above


## NNDy SCRIPT - here comes the fun part
Read carefully through the NNDy.py before running the optimizer as all the degrees of freedom offered and the details that you need to take care of are explained in the comments

As a recap:
<ul>
	<li>Indicate the name of the routine that you want to run - aka the experimet</li>
	<li>Indicate the name of the cost/DA script that - aka the cost function</li>
	<li>Set at least one halting condition</li>
	<li>Set the names, the initial values and the boundaries of the input parameters</li>
</ul>

Optional functionalities
<ul>
	<li>Set values of fixed, global parameters</li>
	<li>Recall as training dataset the data of past runs</li>
	<li>Handle trust region</li>
	<li>Activate update of hyperparameters</li>
</ul>