.. _nnevo_overview:

Overview
====================

.. contents::
    :local:
    :backlinks: none

About
--------------

|The_nextnanoevo_package| is interfacing minimization and evolution algorithms with nextnano simulation tools: |nextnano++|, |nextnano3|, and |nextnano.NEGF|.
The package takes care of proper execution of simulations for optimization algorithms and definitions of problems to optimize based on standard |nextnano| outputs.

The optimization problem that |nextnanoevo| solves is defined in the following way: given a set of input parameters for the device design :math:`[x_1, x_2,...,x_N]` (i.e. input file variables such as thicknesses of layers, temperature, alloy contents, simulation hyperparameters etc) and their respective limits, find such input variables vector that minimizes/maximizes the metric function :math:`f(x_1, x_2,...,x_N)` (i.e. a figure of merit such as quantum efficiency, bandgap, etc).
The objective could be also to have a target value of the metric function :math:`f_{target}`.
In this case, the problem is defined as a minimization problem with the objective to minimize the difference between the target value and the metric function :math:`|f-f_{target}|`.
The |nextnanoevo| package also able to handle multi-objective optimization problems, where the metric function is a vector.
In this case the Pareto dominant solutions are searched for.

The metric function can be a function of the simulation results (i.e. a post-processing function) or a combination of simulation results and input parameters. 

The user can choose between optimization algoritms from scipy.optimize and PyGMO: 

   - SciPy.optimize contains set of deterministic optimization algorithms to solve root and minimization problems. You can visit the documentation `here <https://docs.scipy.org/doc/scipy/reference/optimize.html>`__.

   - PyGMO is a Python library developed by F. Biscani and D. Izzo :ref:`[Biscani2020]<Biscani2020>`. It is an interface facilitating implementation of various evolutionary algorithms such as evolution strategies or genetic algorithms. It can be used to solve many kinds of single- and multi-objective problems.

We recommend using SciPy algorithms to solve simple single-objective problems, while PyGMO is more suited for multi-objective problems as well as for problems that have convergence issues with deterministic algorithms.

Example
--------------

For example, one wants to study an LED with the goal to maximize quantum efficiency (QE) and has an initial design with a QE of 4%.
The user would provide the algorithm with set of parameters that can be modified and the limits for these parameters.
The metric function will be defined as a quantum efficiency and the algorithm will be run to find the optimal design.


Requirements
-------------

To run the |nextnanoevo| module, you need to:

   - have a valid license for |nextnanoevo| 
   - install PyGMO (see `GitHub <https://esa.github.io/pygmo2/install.html>`__)
   - install nextnanoevo
   - prepare configuration file for |nextnanopy| (see `GitHub <https://github.com/nextnanopy/nextnanopy/tree/master/docs/examples>`__)

Installation
-------------

We recommend installing |nextnanoevo| with conda package manager. 
Installation without conda using different python distributions is possible if requirements above are met (but not tested).

.. rubric:: Installation with conda

1. Install `Anaconda <https://www.anaconda.com/download>`__ or `Miniconda <https://docs.conda.io/projects/miniconda/en/latest/>`__

    Miniconda is a lightweight version that install only the minimum necessary liabraries).


2. Create and new conda environment with python 3.10

   .. code-block:: shell
   
      $ conda create -n nnevoEnv python=3.10

3. Activate newly created conda environment

   .. code-block:: shell
   
      $ conda activate nnevoEnv

4. Install pygmo (this step might take few minutes)

   .. code-block:: shell
            
      $ conda config --add channels conda-forge
      $ conda config --set channel_priority strict
      $ conda install pygmo

5. Install nextnanoevo into the activated environment with installation script

   .. code-block:: shell
            
      $ path/to/nextnanoevo/install.bat


License activation
-------------------

The license is activated in the same way as other products, for more details visit `License activation page <https://www.nextnano.com/documentation/getting_started/license_activation/index.html>`_


Config setup
-------------

In order to use nextnanoevo, at least 2 products should be set up in nextnanopy config.

   - nextnanoevo itself (license option only)
   - nextnano product you want to use it with. For example, for nextnano++ you need to set up license, exe, database and output directory

To set up nextnanoevo license, run the following script.

   .. code-block:: python

      import nextnanopy as nn
      nn.config.set('nextnanoevo', 'license', 'path\to\your\License_nnevo.lic')
      nn.config.save()

Tutorial on how to set up other nextnano product can be found here - `Tutorial 0 - Set up the configuration <https://github.com/nextnanopy/nextnanopy/blob/master/docs/examples/Example0_Set_up_the_configuration.ipynb>`_.