Get started
===========

If you want to reach out to contributors and users, please consider joining the chat, see :doc:`./chat`.

See the :doc:`../building/building` section to install the code locally or on your favorite platform.

A full HiPACE++ input file can be found below, with a detailed description of the main parameters.
All the input parameters available in the simulation are available in the :doc:`parameters` section.

.. literalinclude:: ../../../examples/get_started/inputs_normalized

This input file is ``inputs_normalized`` in ``examples/get_started/``, which is the recommended place to start running a first simulation.

After compiling HiPACE++ from the HiPACE++ root directory, execute

.. code-block:: bash

   cd examples/get_started/
   ../../build/bin/hipace inputs_normalized # run the simulation

Then you can use the `openPMD-viewer <https://github.com/openPMD/openPMD-viewer>`__ to read the simulation output data. Directory `examples/get_started/` also contains this :download:`example notebook <../../../examples/get_started/notebook.ipynb>`. Reading the simulation output only takes these few Python commands:

.. code-block:: python

   # import statements
   import numpy as np
   import matplotlib.pyplot as plt
   from openpmd_viewer import OpenPMDTimeSeries
   # from tools/
   import read_insitu_diagnostics as diag
   # Read the simulation data
   ts = OpenPMDTimeSeries('./diags/hdf5/')
   # Get beam and field data at iteration 20
   iteration = 20
   x, z = ts.get_particle(species='beam', iteration=iteration, var_list=['x', 'z'])
   F, m = ts.get_field(field='Ez', iteration=iteration)
   # Read in-situ diagnostics
   ir = diag.InSituReader('./diags/insitu/reduced_beam.*.txt')
   ir.avail()
   # Example plot
   plt.figure(figsize=(7,7), dpi=150)
   plt.plot(ir.time, ir.avg_data("[x]"))
   plt.savefig('./avg_x.png')


Also please have a look at the production runs for beam-driven and laser-driven wakefield:

.. toctree::
    :maxdepth: 1

    inputs_pwfa.rst
    inputs_lwfa.rst

Both use realistic resolutions and run well on modern GPUs (as an estimate, each should take less than 5 min on 16 modern GPUs, e.g., NVIDIA A100).

Additional examples can be found in ``examples/``.