Metadata-Version: 2.1
Name: nse-nn-lpv
Version: 1.0.1
Summary: Helper functions for NSE as LPV with Neural Networks
Home-page: https://gitlab.mpi-magdeburg.mpg.de/cnn-nse-ldlpv/21-nse-nn-lpv
Author: Jan Heiland
Author-email: jnhlnd@gmail.com
Maintainer: Jan Heiland
Maintainer-email: jnhlnd@gmail.com
License: MIT
Description: Convolutional Neural Networks for Semi-discrete NSE
        ---
        
        A `python` module with
        
         * a dynamic setup of *Convolutional Neural Networks* in `PyTorch`
         * an interface to `FEniCS` to generate data from FEM simulations of flows and
         * a numerical realization of FEM norm in the training neural networks
        
        developed to design very low-dimensional LPV approximations of incompressible Navier-Stokes equations.
        
        # The Module
        
        ## Installation
        
        ```sh
        # package for sparse cholesky factorizations 
        # not needed but speed up with FEM norms and POD
        
        apt install libsuitesparse-dev
        pip install scikit-sparse==0.4.5
        
        # fenics -- for the FEM part
        apt install fenics  # see https://fenicsproject.org/download/
        
        # install this module and helper modules
        pip install .  # if to be installed from source
        # pip install nse_nn_lpv  # from the pypi index
        ```
        
        ## Documentation
        
        The underlying principles are explained in the paper
        
        > Benner, Heiland, Bahmani (2022): *Convolutional Neural Networks for Very Low-dimensional LPV Approximations of Incompressible Navier-Stokes Equations* 
        
        that appeared in Frontiers.
        
        This module was the backend of the presented numerical examples.
        
        # Reproducing numerical results
        
        Generally, the numerical procedure consists of
        
        1. generating FEM simulation data
        2. setting up and training the neural networks
        3. running simulations
        
        Step **1.** is defined in the folder `simulations-training-data`. See the corresponding [(simulation) `RUNME.md`](simulations-training-data/RUNME.md)
        
        Steps **2.** and **3.** in the folder `tests`. See the corresponding [(training) `RUNME`](tests/RUNME.md) sh for instructions.
        
        **Note**: The folders and the numerical scripts are part of the complete sources in the git repository under the tag that corresponds to the paper under question or in the dedicated Zenodo repository. The `pypi` distribution only contains the core module.
        
        
        # Data and Handling
        
        Generally, the data is 
        
        1. generated by the simulation
        2. interpolated to *the pictures*
        3. imported to PyTorch as tensors
        
        The relevant formats and routines are as follows:
        
        ```python
        import nse_nn_lpv.nse_data_helpers as ndh
        ```
        
        1. `time_dep_nse_generic.py` computes the trajectories with snapshots `vvec` and interpolates them to the two pictures `vmatx` and `vmaty` at all time instances `ti`. The data is stored as a `json` file, say, `data.json` like
        ```json
        {ti: {'vvec': vvec, 'vmatx': vmatx, 'vmaty': vmaty},
         'femdata': 'information of the simulation ...'}
        ```
        
        2. `(datal, vvecl) = ndh.get_nse_img_data('data.json')` takes the data file `data.json` and returns the data as a list (of tuples) of `numpy` arrays: 
        ```python
        datal = [(vmatx, vmaty, t_0), ..., (vmatx, vmaty, t_end)]
        vvecl = [vvec_0, ..., ..., ..., ..., vvec_end]
        ```
        
        3. `trn_nse_data = ndh.NSEDataset(nsedatal, vvecl)` takes the data lists and makes it available as a `pytorch` data set. In particular, the two *pictures* `vmatx`, `vmaty` are merged into a tensor.
        
        4. `stst_dataloader = pytorch.DataLoader(trn_nse_data, batch_size=1, shuffle=True)` then defines a way to access the data. E.g., 
        ```python
        (ttstset, tstvec) = next(iter(stst_dataloader))
        ```
        returns a data point via
         * `ttstset`: the tensor of size `(batch_size, 2, width, height)`, where `(width, height)` are the dimensions of the *pictures*
         * `tstvec`: the corresponding `vvecs` (needed, e.g., for the loss function later)
        
        # Python Machine-Learning Resources
        
         * an [overview](https://analyticsindiamag.com/top-7-python-neural-network-libraries-for-developers/)
           1. Tensorflow -- see below
           2. Pytorch -- see below
           3. NeuroLab
           4. ffnet
           5. Scikit-Neural Network
           6. Lasagne
           7. pyrenn
        
        ### Tensorflow
        
         * [website](https://www.tensorflow.org/)
         * [Article for understanding NN using TensorFlow](https://towardsdatascience.com/building-your-first-neural-network-in-tensorflow-2-tensorflow-for-hackers-part-i-e1e2f1dfe7a0)
         * Previous experience with building NN
        * Visualization feature [TensorBoard](https://www.tensorflow.org/tensorboard)
        * Based on keras 
        
        ### PyTorch
        
         * [website](https://pytorch.org/)
         * [Tutorial for simple NN](https://pytorch.org/tutorials/beginner/blitz/neural_networks_tutorial.html)
         * Recommended by colleagues (Lessig, Richter)
        
        ### Scikit-Learn
        
         * [website](https://scikit-learn.org/stable/index.html)
         * looks well maintained
         * many routines for data processing
         * a few on neural network
        
        
Platform: UNKNOWN
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Description-Content-Type: text/markdown
