# Vlasiator.jl

Vlasiator.jl is a data processing and analyzing tool for the numerical model for collisionless ion-kinetic plasma physics Vlasiator. This lightweight package is built upon its sister in Python Analysator and carefully designed for performance, capability and ease of use. It can be easily integrated with external packages like FieldTracer.jl and TestParticle.jl to do all kinds of in-depth analysis.

Vlasiator.jl contains the following features:

- Reading VLSV format data.
- Calculating derived quantities from raw VLSV outputs.
- Extracting quantities at a given point/line/plane/box.
- Plotting 1D curves/2D cuts of saved/derived variables and phase space distributions.
- Analyzing velocity distribution functions.
- Appending DCCRG arrays to VLSV files.
- Converting selected domain and variables from VLSV into VTK format for data analysis and visualization in ParaView and VisIt.
- Monitoring Vlasiator run log files.

This package mostly aims at supporting Vlasiator 5.0+. Older versions of Vlasiator has different naming standards for outputs, and is not guaranteed to work. The full naming standards are described in the analysator wiki page.

## What is Vlasiator

Vlasiator solves the Vlasov–Maxwell system of equations for ions while assuming massless electrons under the quasi-neutrality condition $\sum_\alpha n_\alpha q_\alpha \approx e n_e$. The fundamental description of charged particle motion in an electromagnetic field is given by the Vlasov equation

\[\frac{\partial f_\alpha}{\partial t} + \mathbf{v}\cdot\frac{\partial f_\alpha}{\partial \mathbf{r}} + \frac{q_\alpha}{m_\alpha}(\mathbf{E}+\mathbf{v}\times\mathbf{B})\cdot \frac{\partial f_\alpha}{\partial \mathbf{v}} = 0\]

where $\alpha$ denotes the particle species, $\mathbf{r}$ and $\mathbf{v}$ are the spatial and velocity coordinates, $f_\alpha(\mathbf{r},\mathbf{v},t)$ is the six-dimensional phase-space density of a particle species with mass $m_\alpha$ and charge $q_\alpha$, and acceleration $\mathbf{a}$ is given by the Lorentz force with $\mathbf{E}$ and $\mathbf{B}$ are the electric and magnetic field, respectively.

The zeroth and first moments of plasma, ion density $n_\alpha$ and velocity $\mathbf{u}_\alpha$, are obtained as integrals of the ion velocity distribution function

\[\begin{aligned} n_\alpha &= \int f_\alpha(\mathbf{r},\mathbf{v},t)\mathrm{d}\mathbf{v} \\ \mathbf{u}_\alpha &= \frac{1}{n_\alpha}\int \mathbf{v}f_\alpha(\mathbf{r},\mathbf{v},t)\mathrm{d}\mathbf{v} \end{aligned}\]

The magnetic field is updated using Faraday's law:

\[\nabla \times \mathbf{E} = -\frac{\partial \mathbf{B}}{\partial t}\]

and the electric field is given by the generalized Ohm's law:

\[\mathbf{E} = -\frac{\sum_\alpha n_\alpha q_\alpha\mathbf{u}_\alpha}{\sum_\alpha n_\alpha q_\alpha} \times\mathbf{B} + \frac{1}{\sum_\alpha n_\alpha q_\alpha}\mathbf{J}\times\mathbf{B} - \frac{1}{\sum_\alpha n_\alpha q_\alpha}\nabla\cdot\overleftrightarrow{P}_e + \eta \mathbf{J}\]

The four terms on the right-handed side are the convection term, the Hall term, the electron pressure gradient term, and the resistive term, respectively. For multi-ion species, the convection velocity is the charge averaged ion velocity. The total current density $\mathbf{J}$ is obtained from Ampère's law where the displacement current has been neglected:

\[\nabla\times\mathbf{B} = \mu_0 \mathbf{J}\]

Finally, by determining the electron pressure tensor by using an appropriate equation of state, the evolution of the system can be followed in time. For example, let $\overleftrightarrow{P}_e = p_e \overleftrightarrow{I}$ where $p_e$ is the isotropic scalar electron pressure. In an isothermal process,

\[p_e = n_e k_B T_e\]

where $n_e \approx n_i$ and $T_e$ is a constant. In an adiabatic process with index $\gamma$,

\[p_e / n_e^\gamma = \text{const.}\]

The different processes can be generalized into the polytropic process:

\[p_e / n_e^n = \text{const.}\]

When the ideal gas law applies, the *polytropic index* $n=1$ for an isothermal process, and $n=\gamma$ for an adiabatic process.

For more details, please refer to Vlasov methods in space physics and astrophysics.

## Getting started

To install,

```
julia> ]
pkg> add Vlasiator
```

You can then use the package via

`julia> using Vlasiator`

### Visualization

- PyPlot

If you aim at using Matplotlib, besides adding `PyPlot`

and the Vlasiator specific wrapper `VlasiatorPyPlot`

, you should also link to a preinstalled Python version by setting the environment variable and building the PyCall package

```
ENV["PYTHON"]="your python executable"
Pkg.build("PyCall")
```

If `ENV["PYTHON"] = ""`

before building, a private Python distribution will be installed via Miniconda. Details are described in automated matplotlib installation.

- Makie

You can add Makie.jl and VlasiatorMakie.jl through the pkg manger. The sub-package VlasiatorMakie provides user recipes for Makie.

- Plots

Add Plots.jl through the pkg manager. Built-in user recipes for Plots are provided.

## Author

This module is written by Hongyang Zhou. For citing Vlasiator.jl, please refer to .