.. _nnevo_definitions:

Definitions
===========

   .. note::
      |The_nextnanoevo_package| is under development. 



The optimization procedure is defined by vector of input variables, *metric* to be optimized (also called *fitness* for some algorithm), and *function* that converts input variabels to metric.

To be able to define these parameters of  optimization procedure in nextnanoevo, 2 key instances should be created: *NextnanoIO* and *NextnanoMetricExtractor*.

nextnanoevo.IO
-------------------

IO stands for nextnano input-output. This class defines:

    - *input_file_path*: input file to run
    - *input_variable_names*: variables to variate in the input file
    - *target_output*: output datafiles that will be used

To create IO instance, use the following syntax

    .. code-block:: python

        from nextnanoevo.IO import IO
        
        input_file_path = r'\path\to\input_file.in'

        variables = ['variable_name1', 'variable_name2']
        # example: variables = ['WellWidth', 'BarrierWidth']

        output_files = [('relative', 'path', 'datafile1'),
                        ('relative', 'path', 'datafile2')]
        
        # the path of output files is relative to output directory
        # example: output_files = [('Strain', 'strain_simulation.dat'),
        #                          ('bias_00000', 'Quantum', 'energy_spectrum_quantum_region_Gamma_00000.dat')]

        nn_io = IO(input_file_path, variables, output_files)




Metric
-----------------------

This class defines:

    - *input_length*: number of datafiles that will be processed (should match with NextnanoIO)
    - *output_length*: dimensionality of the metric vector
    - *extraction_function*: how to extract the final metric vector from the datafiles (the function output should match with *output_length*)

Extraction function is defined by user. 
The extraction function will take as input list of nextnanopy datafiles.
Visit this tutorial to get to know about nextnanopy datafiles `Tutorial 2 - Plotting data files <https://github.com/nextnanopy/nextnanopy/blob/master/docs/examples/Example2_Plotting_data_files.ipynb>`_.


To create *Metric* instance, use the following syntax

    .. code-block:: python

        from nextnanoevo.MetricExtractor import Metric
        import numpy as np


        def dummy_extraction_function(dfiles):
            """
            This is an example of simple extraction function that takes first value of first variable from 2 datafiles.
            Reutrn the vector contatining sum and product of these values.
            """
            dfile1 = dfiles[0]
            dfile2 = dfiles[1]

            val1 = dfile1.variables[0].value[0]
            val2 = dfile1.variables[0].value[0]

            return np.array([val1+val2, val1*val2])        
        

        nn_metric = Metric(input_length=2, output_length=2, extraction_function=dummy_extraction_function)

        # input_length = 2, because the metric processes 2 datafiles
        # output_length = 2, because it returns vector of length 2.

In some cases, the metric function can be dependent on the input variables. 
The workaround to achieve this is to use the output file that contains the input paramters (:guilabel:`variables_input.txt` in case of |nextnano++|).
Lets have a look at the dummy example with metric dependent on one value from output file and one input variable.

    .. code-block:: python

        from nextnanoevo.IO import IO
        from nextnanoevo.MetricExtractor import Metric 

        # first, we define the IO instance with one normal output file and one output file with input variables
        input_file_path = r'\path\to\input_file.in'

        variables = ['variable_name1']
        output_files = [('relative', 'path', 'datafile'),
                        ('variables_input.txt', )]   

        nn_io = IO(input_file_path, variables, output_files)

        def dummy_extraction_function_with_input(dfiles):
            """
            Example of extraction function that takes first value of datafile and input varibale and returns the ratio
            """
            dfile = dfiles[0]
            input_variables_dfile = dfiles[1]

            value = dfile.variables[0].value[0]
            input_value = input_variables_dfile.variables[0].value

            

            return np.array([value/input_value])       

        nn_metric = Metric(input_length=2, output_length=1, extraction_function=dummy_extraction_function_with_input)

        # input_length = 2, because the metric processes 2 datafiles
        # output_length = 1, because it returns vector of length 1.