.. _quick_start_guide:
*****************
Quick start guide
*****************
The Pencil Code is an open-source simulation code written mainly in Fortran
and released under the GPL license. General information can be found at our
official `homepage `__.
This guide is a concise, self-contained introduction to the essentials:
downloading, compiling, running, and post-processing your first simulation.
It is designed to get you from zero to scientifically meaningful output with
as little friction as possible.
For deeper explanations, theoretical background, and the full feature set,
please refer to the :ref:`manual`.
Required software
=================
The Pencil Code runs best on Unix-like systems. Below are brief instructions
for GNU/Linux and macOS users. Other systems are welcome to join, but results
may vary depending on compiler mood and cosmic alignment.
GNU/Linux
----------
You will need both a Fortran and a C compiler to build the code. They should
belong to the same distribution and version (for instance, GNU GCC or Intel
compilers). If you can run ``gfortran --version`` and get a friendly response,
you are halfway there.
MacOS X
-------
On macOS, the easiest route is to install Xcode from
``_ (registration required).
Alternatively, you can
install a ``gfortran`` binary package from
http://gcc.gnu.org/wiki/GFortranBinaries.
Download the archive and use the
included installer. It installs into ``/usr/local/gfortran`` and provides a
symbolic link in ``/usr/local/bin/gfortran``.
You may need to add the following line to your “``.cshrc``” file in your
``/home`` directory:
.. code:: csh
setenv PATH /usr/local/bin:\$PATH
Download the Pencil Code
========================
For full details, see :ref:`download`. The short version: use Git.
.. code:: bash
git clone https://github.com/pencil-code/pencil-code.git
That will create a directory named ``pencil-code`` containing everything you
need. Congratulations — you now own a respectable quantity of Fortran.
Configure the shell environment
===============================
Before doing anything else, you need to load the environment variables used by
the Pencil Code tools. Move into the freshly downloaded directory:
.. code:: bash
cd pencil-code
If you use a ``sh``-compatible shell (such as ``bash``), simply type:
.. code:: bash
bash sourceme.sh
For more details, see :ref:`man1_environment_settings`.
Quick look at the code structure
================================
The downloaded ``pencil-code`` directory contains several subdirectories:
* ``doc`` – Documentation sources, including :file:`manual.pdf` and other
supporting material.
* ``samples`` – A collection of ready-to-run example problems.
* ``config`` – Configuration files for compilation and setup.
* ``src`` – The actual source code.
* ``bin`` and ``lib`` – Supplemental scripts and libraries.
* ``idl``, ``python``, ``julia``, etc. – Post-processing tools in various languages.
For a detailed explanation, see :ref:`man1_directory_tree`.
Your first simulation run
=========================
Every |PC| simulation requires a set of configuration and source files. Some
define physical parameters and numerical settings, others handle the Fortran
source modules. See :ref:`man1_files_in_rundir` for a deeper explanation.
The easiest way to start is by using one of the pre-configured sample problems.
Here we will use ``pencil-code/samples/conv-slab``.
Create a new run-directory
--------------------------
Create a new directory for your simulation and copy the contents of the sample
setup:
.. code:: bash
mkdir -p myuser/test
cd myuser/test
cp -r $PENCIL_HOME/samples/conv-slab/* .
Choose your run directory wisely. Simulations can generate a substantial amount
of data, so avoid using locations with strict storage quotas, such as your home
directory on shared systems.
Linking to the sources
----------------------
To connect your run directory with the main Pencil Code source directory, run:
.. code:: bash
pc_setupsrc
This creates the required symbolic links. See
:ref:`man1_linking_scripts_and_source` for more information.
Makefile and parameters
-----------------------
Two local configuration files define the essential parts of a simulation setup:
* ``src/Makefile.local`` – Lists the modules to be used.
* ``src/cparam.local`` – Defines the grid size and number of processors.
Take a look at these files before running. They are short but powerful.
Single-processor
^^^^^^^^^^^^^^^^
A minimal ``src/Makefile.local`` for a single-processor run could be:
.. code:: fortran
MPICOMM=nompicomm
In ``src/cparam.local``, set the number of processors to ``1`` accordingly:
.. code:: fortran
integer, parameter :: ncpus=1,nprocx=1,nprocy=1,nprocz=ncpus/(nprocx*nprocy)
integer, parameter :: nxgrid=32,nygrid=nxgrid,nzgrid=nxgrid
Multi-processor
^^^^^^^^^^^^^^^^
To use MPI for multi-processor simulations, make sure an MPI library is
installed and update your configuration in ``src/Makefile.local``:
.. code:: fortran
MPICOMM=mpicomm
Adjust ``ncpus`` in ``src/cparam.local`` to match your processor layout. A
good rule of thumb is to keep 32 grid points along the x-direction to make
efficient use of SIMD units. To compile, use a configuration file with the
``_MPI`` suffix, as shown below.
Compilation
------------
To compile the code with default GNU compilers (single processor), simply run [#]_ :
.. code:: bash
pc_build
For a multi-processor build using MPI:
.. code:: bash
pc_build -f GNU-GCC_MPI
.. note::
Depending on your system, a simpler :command:`pc_build` can also work for a multi-processor build.
For additional details, see :ref:`man1_quick_instructions`.
.. [#] You can use a pre-defined configuration file corresponding to your compiler package. E.g. the default compilers are ``gfortran`` together with ``gcc`` and the code is being built with the default options (not using MPI)
Using a different compiler (optional)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you wish to use a different compiler package (for example, Intel or Cray),
try one of the following:
.. code:: bash
pc_build -f Intel
pc_build -f Intel_MPI
pc_build -f Cray
pc_build -f Cray_MPI
Additional predefined configurations can be found in
``pencil-code/config/compilers/*.conf``.
Changing compiler options (optional)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You can also define host-specific configuration files in
``pencil-code/config/hosts/``. By default, :command:`pc_build` searches for a
file based on your host ID, which you can view with:
.. code:: bash
pc_build -i
You may add your own configuration file as ``host-ID.conf`` and adjust compiler
flags as needed. A good example to adapt is
``pencil-code/config/hosts/IWF/host-andromeda-GNU_Linux-Linux.conf``.
To clean up all generated files:
.. code:: bash
pc_build --cleanall
Running...
----------
Set up your simulation by editing the following files:
* ``start.in`` – Initial conditions.
* ``run.in`` – Main runtime parameters.
* ``print.in`` – Select which quantities appear in ``data/time_series.dat``.
Make sure an empty ``data/`` directory exists:
.. code:: bash
mkdir data
Now, launch the simulation:
.. code:: bash
pc_run
If everything is working correctly, the output should include:
.. code:: text
start.x has completed successfully
Once initialized, the code will begin printing quantities to the console, such
as:
.. code:: text
--it-----t-------dt------urms----umax----rhom----ssm----dtc---dtu---dtnu-dtchi-
0 0.00 6.793E-03 0.0063 0.0956 14.4708 -0.4460 0.978 0.025 0.207 0.345
10 0.07 6.793E-03 0.0056 0.0723 14.4708 -0.4464 0.978 0.019 0.207 0.345
20 0.14 6.793E-03 0.0053 0.0471 14.4709 -0.4467 0.978 0.019 0.207 0.345
.......
When finished, you should see:
.. code:: text
Simulation finished after xxxx time-steps
.....
Wall clock time/timestep/meshpoint [microsec] = ...
An empty file named ``COMPLETED`` will appear in your run directory when the
simulation ends.
To verify your results against the reference output for this sample, run:
.. code:: bash
diff reference.out data/time_series.dat
If they match, congratulations — your setup is alive and calculating.
Troubleshooting...
------------------
If compilation fails, try cleaning and rebuilding (optionally with MPI):
.. code:: bash
pc_build --cleanall
pc_build -f GNU-GCC_MPI
If issues persist, please report them on our mailing list:
http://pencil-code.nordita.org/contact.php. Include the exact step that failed,
the error message, and confirm that all required steps above were followed.
Also include your operating system, shell type, and the full output of:
.. code:: bash
bash
cd path/to/your/pencil-code/
source sourceme.sh
echo $PENCIL_HOME
ls -la $PENCIL_HOME/bin
cd samples/1d-tests/jeans-x/
gcc --version
gfortran --version
pc_build --cleanall
pc_build -d
If using MPI, please also include:
.. code:: bash
mpicc --version
mpif90 --version
mpiexec --version
Welcome to the world of Pencil Code — may your runs be stable and your :abbr:`CFL (Courant-Friedrichs-Lewy condition)`
numbers merciful.
Data post-processing
====================
IDL visualization (optional,)
-----------------------------------------
GUI-based visualization (recommended for quick inspection)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The most simple approach to visualize a Cartesian grid setup is to run
the Pencil Code GUI and to select the files and physical quantities you
want to see:
.. code:: idl
IDL> .r pc_gui
If you miss some physical quantities, you might want to extend the two
IDL routines ``pc_get_quantity`` and ``pc_check_quantities``. Anything
implemented there will be available in the GUI, too.
Command-line based processing of “big data”
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Please check the documentation inside these files:
+------------------------------------------------+--------------------------------------------+
|``pencil-code/idl/read/pc_read_var_raw.pro`` | efficient reading of raw data |
+------------------------------------------------+--------------------------------------------+
|``pencil-code/idl/read/pc_read_subvol_raw.pro`` | reading of sub-volumes |
+------------------------------------------------+--------------------------------------------+
|``pencil-code/idl/read/pc_read_slice_raw.pro`` | reading of any 2D slice from 3D snapshots |
+------------------------------------------------+--------------------------------------------+
|``pencil-code/idl/pc_get_quantity.pro`` | compute physical quantities out of raw data|
+------------------------------------------------+--------------------------------------------+
|``pencil-code/idl/pc_check_quantities.pro`` | dependency checking of physical quantities |
+------------------------------------------------+--------------------------------------------+
in order to read data efficiently and compute quantities in physical
units.
Command-line based data analysis (may be inefficient)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Several idl-procedures have been written (see in ‘``pencil-code/idl``’)
to facilitate inspecting the data that can be found in raw format in
‘``jeans-x/data``’. For example, let us inspect the time series data
.. code:: idl
IDL> pc_read_ts, obj=ts
The structure ``ts`` contains several variables that can be inspected by
.. code:: idl
IDL> help, ts, /structure
** Structure <911fa8>, 4 tags, length=320, data length=320, refs=1:
IT LONG Array[20]
T FLOAT Array[20]
UMAX FLOAT Array[20]
RHOMAX FLOAT Array[20]
The diagnostic ``UMAX``, the maximal velocity, is available since it was
set in “``jeans-x/print.in``”. Please check the manual for more
information about the input files.
We plot now the evolution of ``UMAX`` after the initial perturbation
that is defined in “``start.in``”:
.. code:: idl
IDL> plot, ts.t, alog(ts.umax)
The complete state of the simulation is saved as snapshot files in
“``jeans-x/data/proc0/VAR*``” every ``dsnap`` time units, as defined in
“``jeans-x/run.in``”. These snapshots, for example “``VAR5``”, can be
loaded with:
.. code:: idl
IDL> pc_read_var, obj=ff, varfile="VAR5", /trimall
Similarly ``tag_names`` will provide us with the available variables:
.. code:: idl
IDL> print, tag_names(ff)
T X Y Z DX DY DZ UU LNRHO POTSELF
The logarithm of the density can be inspected by using a GUI:
.. code:: idl
IDL> cslice, ff.lnrho
Of course, for scripting one might use any quantity from the ``ff``
structure, like calculating the average density:
.. code:: idl
IDL> print, mean(exp(ff.lnrho))
Python visualization (optional)
-------------------------------
Be advised that the Python support is still not complete or as
feature-rich as for IDL. Furthermore, we move to Python3 in 2020, and
not all the routines have been updated yet.
Python module requirements
^^^^^^^^^^^^^^^^^^^^^^^^^^^
In this example we use the modules: ``numpy`` and ``matplotlib``. A
complete list of required module is included in
“``pencil-code/python/pencil/README``”.
Using the ``pencil`` module
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
After sourcing the “``sourceme.sh``” script (see above), you should be
able to import the ``pencil`` module:
.. code:: python
import pencil as pc
Some useful functions:
=============================== ======
``pc.read.ts`` read “``time_series.dat``” file. Parameters are added as members of the class
``pc.read.slices`` read 2D slice files and return two arrays: (nslices,vsize,hsize) and (time)
``pc.visu.animate_interactive`` assemble a 2D animation from a 3D array
=============================== ======
Some examples of postprocessing with Python can be found in the
:ref:` python documentation ` and in the :ref:` python tutorials `.