HOWTO define the DA script for NNDy

complete commenting added with instructions for writing an analysis script that is compatible with NNDy optimizer and returns the cost associated with the run just performed

scripts/DA/TestDA.py

@@ -9,6 +9,7 @@ import lmfit
 from matplotlib import pyplot as plt
 
 
+#here it looks for the DA file, if not in the same folder as NNDy you can specify the folder in new_path
 new_path = r'C:\Users\DyLab\PrepLab\Data_Analysis' 
 if new_path not in sys.path:
     sys.path.append(new_path)
@@ -17,22 +18,34 @@ from Analyser.FitAnalyser import Gaussian2dModel
 from Analyser.FitAnalyser import FitAnalyser
 from ToolFunction.ToolFunction import get_scanAxis
 
+#reference values measured without AOM for 5 minutes
 free_std = 1.815672e-6 #THz
 free_freq = 438.585992 #THz
 free_intensity_max = 186
 
+
+#handling relative weight in the cost scaling
 cost_scaling_factor = {
     'red_chi2': 0.01,
     'std_freq': 1,
     'peak_intensity': 10
 }
 
-
+#    THE COST FUNCTION
+#
+#in every DA script for NNDy we need a cost function defined as below
 def cost(hdf_outfile):
+    #takes as argument:
+    #       the hdf5 file of the shot, where it can read the data of the shot and the global variables
+    #return:
+    #       dictionary with 'cost' item - and uncertainity if available- or 'bad' : True for a bad run
+    #it would be better if you return all three items everytime, but the code can handle if you don't
 
+    #then the role of the cost function is to initiate the analysis and obtain the values of the observables of interest from which you want to calculate the cost
     output = analysis(hdf_outfile)
     print(f'output:\n{output}')
 
+    # recommended way to handle bad runs
     if output['bad']:
         return {
             'cost': np.inf,
@@ -56,6 +69,9 @@ def cost(hdf_outfile):
         'bad': False 
     }
 
+
+#this function is called within cost and is the one which handles the analysis
+#it should be substituted with the imports that will execute the analysis or a custom function like this one
 def analysis(hdf_outfile):
     bad = False
     group_name = 'DA'
@@ -115,7 +131,7 @@ def analysis(hdf_outfile):
     #print(output)
     return output
 
-
+#subprocess called within the analysis routine
 def img_Analyzer(image):
 
     dimensions = ['x', 'y']