# neurosynchro¶

*Neurosynchro* is a small Python package for creating and using neural
networks to quickly approximate the coefficients needed for fully-polarized
synchrotron radiative transfer. It builds on the Keras
deep learning library and is licensed under the MIT License.

This documentation refers to version 0.1 of *neurosynchro*.

- Take me to the tutorial where I get to train some neural networks! (The training can take a few hours if you’re on a laptop, though.)
- Take me to the tutorial where I just calculate some coefficients! (This tutorial is much quicker … maybe too quick.)

# Who It’s For¶

*Neurosynchro* solves a very specific problem.

*You* are a person that wants to perform some numerical radiative transfer of synchrotron radiation in the Stokes basis. In this problem, for each
point in space you need to calculate eight matrix coefficients: three numbers
describing emission (total intensity, linear polarization, and circular
polarization), three describing absorption, and two “Faraday terms” (rotation
of linear polarization, conversion of circular and linear).

You have a code, such as Rimphony or Symphony, that can calculate these numbers for you as a function of some input physical parameters such as an electron temperature or an energy power law index. You also have a code such as grtrans that can perform your radiative transfer integration in the Stokes basis.

The problem is that your synchrotron calculator code is very precise but it’s
just *too slow* for your needs: you need to do lots of integrations for
arbitrary input parameters, and things are taking too long.

Enter *neurosynchro*. This package provides a toolkit for training neural
networks to quickly approximate the coefficients you need. Once you’ve trained
your network, you can get very good approximations of the necessary
coefficients really quickly — something like 10,000 times faster than the
detailed calculations.

# Installation¶

# Tutorial, AKA, How to Use It¶

There are three main ways that you might use *neurosynchro*:

- You might have the data files for a useful, trained neural network on hand. In this case, all you need to do is load it up and use it. We have provided sample trained neural networks for download — the above page walks you through downloading them. So, this is the quickest way to get started.
- You might have a training set on hand, but not have created your neural networks. In this case, you need to go through the process of training a new set of neural networks. Once again, an example training set is available for download. The training takes a few dozen core-hours of CPU time, so it can take a little while.
- Finally, if you are investigating a new or unusual region of parameter
space, you might not even have an existing training set to work with. In
this case you will need to start at the very beginning by making your
own training set. How you do so is beyond the purview
of
*neurosynchro*, but in the above pages we document the format that the training data must obey.

Or, to break down the various steps in roughly sequential order:

- Make Your Training Set
- Download a Sample Training Set
- Transform Your Training Set
- Specify Your Parameter Transformations
- Precalculate the Domain and Range of Your Training Set
- Train Your Networks
- Download Some Pre-Trained Neural Network Data
- Run Some Test Problems
- Use Your Networks for Your Application

# Python API Reference¶

In most cases, the only part of the Python API that you will care about is the
`neurosynchro.impl.PhysicalApproximator`

class — this is the class that
loads up a neural network and computes coefficients for you. The rest of
*neurosynchro*’s functionality is best accessed through the command-line
interface `neurosynchro`

, rather than directly using the Python code. As
such, many internal parts of the code are not documented.

# Contributing to the Project¶

Contributions are welcome! See the CONTRIBUTING.md file attached to the project’s GitHub repository. The goal is to run the project with standard open-source best practices. We do wish to call your attention to the code of conduct, however. Participation in the project is contingent on abiding by the code in both letter and spirit.