Quickstart


This page is designed to guide you through the installation process and through your first 2D simulation with Zeltron on a single processor on your personal computer. The default setup of the code is for a relativistic reconnection simulation, with 2 anti-parallel Harris sheets in a doubly periodic box (see e.g., Cerutti et al. 2013 for more details).

  • Step 1: External libraries and dependencies

    • Zeltron requires only a few external libraries to run:

    - A Fortran compiler, for instance: gcc, intel.

    - The GNU Make

    - The Message Passing Interface library, for instance: openmpi, MPICH.

    - The HDF5 library for parallel data dumping (optional, we will not need it in this tutorial).

    - Your favorite visualization tool: Python-matplotlib, gnuplot, R, IDL, etc...

  • Step 2: Download and install

    • Download the current version of the code using the Zeltron-code GitHub repository. This operation will create a new directory called ~/Zeltron-code/ that contains all source files spread over four subdirectories: one for the 2D Cartesien version, one for the 3D Cartesian code, and two directories containing simple Python scripts to visualize the output from the simulations.

  • Step 3: Compile

    • Move into the 2D code directory,

    $ cd Zelton1.0/Zeltron2D/

    and open the file called "Makefile". After the file header, the first lines should read as:

    # ---------------------Macro-Defs-----------------------------
## Common options for F90 are: ftn, h5pfc, mpif90
F90=mpif90

    Please enter your MPI compiler here, the default is mpif90. Once done, return to the terminal and execute the Makefile:

    $ make IO=txt

    The argument "IO=txt" means that the code will dump data in the text format. For large simulations, it is recommended to use the HDF5 format. Then the argument should be "IO=h5", but for the purpose of this tutorial, we will stick to text files.

  • Step 4: Run

    • If the compilation was successful, the executable file zeltron.exe should have been created. To run a simulation, please use the bash script script_run.sh. This script will: (1) remove old data and compiled files, (2) create new folders that will collect the simulation data, (3) compile and (4) run the code. This means that you will not have to repeat the compilation described in step 3 anymore.

    Open "script_run.sh" with a text editor, the last command should read as:

    # Run the code
mpirun -np 1 zeltron.exe

    This is the Open MPI command to run the code on a single processor (the "-np 1" option is set by default). If you are using a different MPI library, please refer to the manual to identify the command to start the executable file.

    To make the script executable, type:

    ./Zelton1.0/Zeltron2D$ chmod +x script_run.sh

    To run the script, type:

    ./Zelton1.0/Zeltron2D$ ./script_run.sh

    At this point, the code should be running!

  • Step 5: Visualize the output

    • After a few minutes, the code should have completed the simulation. It is time now to look at the output. By default, Zeltron writes data to disk 4 times: one at the initial stage, one at the final stage (after 1500 time steps), and two in between (after 500 and 1000 time steps). All data are dumped in the ./Zeltron1.0/Zeltron2D/data directory.

    You should find a few simple Python-matplotlib scripts along with the source files in the ./Zeltron1.0/plot2D directory. To visualize the time history of the different energy components (e.g., magnetic, particles, etc...) type:

    ./Zeltron1.0/plot2D$ python energy.py &

    Then, you should see something like this:



    Notice the dip in the magnetic energy and the increase in the particle energy after about 500 time steps. This is magnetic reconnection and particle acceleration happening!

    Finally, let's look at the final plasma and magnetic field lines. To do this, use the following command:

    ./Zeltron1.0/plot2D$ python plot_density.py 1500 ions &

    Where the arguments gives the time step and species to display. You should see something similar to this:



    where the white lines shows the in-plane magnetic field lines (isocontours of the magnetic flux function). If so, congratulations! You have run your first simulation with Zeltron. Other basic Python scripts are also provided with the code: plot_current.py, plot_spectrum.py, and timestep.py.

    Enjoy!

    Interested in 3D simulations?

    Go to the ./Zeltron1.0/Zeltron3D directory and simply follow the same procedure. A few Mayavi scripts are also available in the ./Zeltron1.0/plot3D directory for 3D visualization of the data.