abcgan 4.0.0

Generator and Discriminator for Atmosense Background Characterization

ABCGAN

This project uses a generative adversarial network (GAN) to produce a Generator and a Discriminator to characterize the normal atmospheric background. It provides the ability to sample atmospheric parameters, creating full altitude profiles of the sampled measurements. The current system is trained on over 10 years of Incoherent Scatter Radar data collected in Alaska at the Poker Flat Research Range.

Currently the project supports the sampling of low frequency measurements conditioned on high altitude drivers (solar flux, solar zenith angle, etc.). The project goal is to augment this initial capability through generation of high frequency distrubances (waves) as well as allowing conditioning on ground based drivers (terrain, etc.).

Installing abcgan

This package is available on PyPI and can be installed with pip. It is best to do this in a Python virtual environment:

python -m venv venv
. venv/bin/activate

pip install abcgan

It requires Python 3.8+ and uses PyTorch 1.8+.

Downloading the tutorials

The tutorials are available as Jupyter notebooks and are located along with sample data in the tutorial directory in the github repository. You can download these tutorials with the abcgan-cmd program which is installed along with the abcgan package.

After downloading the tutorials, install the required packages listed in tutorials/requirements.txt using pip. You can then start Jupyter Lab and load the tutorial notebook tutorial/demo.ipynb.

The data files and models used in the tutorials are approximately 600Mb in size. Use the -m flag to abcgan-cmd to download them with the tutorials.

abcgan-cmd -m download tutorials
pip install -r tutorials/requirements.txt

jupyter lab 

Running the tutorials on Binder

You can run the tutorial notebooks at any time on Binder. A Docker container will be automatically created with the abcgan package and tutorials.

https://mybinder.org/v2/gh/sri-geospace/atmosense-abcgan/HEAD?labpath=tutorials%2Fdemo.ipynb

Contents

The content of this repository entails:

• Source code inside 'src/abcgan'
• Test code inside 'test'
• Tutorials inside 'tutorials'
• Pre-trained models inside 'models'
• Helper scripts in 'contrib'

Installation from source

Install Pytorch from the Pytorch page Pytorch installation will be specific to your system configuraiton depending on gpu availability and drivers.

git clone https://github.com/sri-geospace/atmosense-abcgan.git

For end user installation:

pip install atmosense-abcgan 

For development:

pip install -e atmosense-abcgan 

Building the documentation

The package documentation is available on Read the Docs. You may also build the docs locatlly. The configuration files and document sources are in the docs/ directory, including a requirements file with the necessary dependencies.

cd docs
pip install -r requirements.txt
make html

The API source files are generated using api-doc:

sphinx-apidoc -o . ../src/abcgan

Note that .rst files are generated from the installed module not the source tree; to reference local changes make sure the installation is performed with pip install -e .

Add the lines to conf.py if not there already:

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   abcgan
   modules

Finally, build the docs:

make clean
make html

Run tests

Make sure to have completed the development. From the top level directory 'atomesense-abcgan' run:

python -m unittest

Using the library

This is a library that can be imported directly in python and used. For example usage see 'tutorials/demo.py'.

Contact

For questions please contact Andrew Silberfarb [e-mail]