Walkthrough

This section highlights the capabilities of the Acherus package and provides practical guidance, including comments on the input parameters required to run a simulation.

Note

Since Acherus was developed for future atmospheric lasing studies, the example images used throughout this guide focuses on infrared picosecond laser filamentation in air, a canonical case for filament-initiated nitrogen lasers.

The guide offers a detailed, step-by-step walkthrough on configuring the input parameters and accessing or visualizing the computed laser and filament data.

Configuration file

The acherus package uses a simple configuration or parameter file to provide every single piece of information needed before, during, and after running each simulation. This simple approach is aligned with most numerical computing projects written in compiled languages, such as C, C++, and Fortran; whereas most Python packages require the user to generate their own script, import third-party libraries or modules, and import package-specific classes or modules that will allow to run the simulation. Once these external tools are imported, the user is further asked to provide them with suitable data variables, which are usually obtained by inserting inside the script additional lines of code. One major advantage of the configuration file is it removes this procedure entirely, leaving imports and preliminary computations to the package internal engine. In acherus, the user provides a collection of inputs, runs the process, and obtains a collection of outputs.

The configuration file structure—from now on until the end of this section will be named example.toml—consists of different <key>=<value> pairs under several sections or “headers” which divide the file in chunks. Each section name is surrounded by squared braces [<section_name>] and comments using the # symbol are ignored. Here is an example:

[medium_parameters.water] # This is a section or header for the `water` option
# The lines below are <key>-<value> option pairs given by the user
nonlinear_index = 4.1e-20
energy_gap = 6.5
collision_time = 1e-15
neutral_density = 6.7e28
initial_density = 1e9

As mentioned before, example.toml determines every aspect regarding the simulation. This implies some sections and <key>-<value> pairs are optional, depending on the nature of the problem. When the section header is <section_name>.<option>, the user must choose one valid <option> string from the set of available choices. Let’s introduce the various options acherus package can receive from example.toml as input parameters.

Note

Keep in mind the order in which different section headers and option pairs are given is irrelevant inside the configuration file. The user is required to provide existing names for sections and their respective option pairs, but neither word order nor letter format come into consideration here. Unless explicitly stated, units used follow the Internal System of Units (SI).

Output paths

The example.toml file admits two output paths key options. They are denoted by data_output_path and figure_output_path for storage of simulation data/figures while/after program execution. The user must provide one string for each value pointing to the exact path where data/figures will be saved. An example would be:

# Example of output paths for simulations results relative to the working directory
data_output_path = "./results/example_data" # example_data/ folder contains the data outputs
figure_output_path = "./results/example_figures" # example_figures/ contains the data figures

Since both the data and figure path parameters are optional, the user may omit them or comment out their corresponding keys. In that case, acherus saves data outputs by default in the working directory under the folder results/, and the figure outputs under results/figures. In general, the default figure output path is <data_output_path>/figures, where <data_output_path> might be either the default string results or another path specified by the user.

The data files are stored in .h5 format with high compression settings using the h5py library, while the figures are lightweight .png files generated with Matplotlib.

Note

Even for (2+1)-dimensional simulations, the output data files size stored inside the chosen folder can be quite large (a few gigabytes) for some laser filamentation problems. Most modern machines and personal laptops have plenty of disk space to store them, but it is recommended to provide a relative path outside the working or home directories to store the files for disk-intensive data outputs.

Execution backends and numerical frameworks

For now, acherus only supports CPU execution as a backend, but we plan to provide GPU-acceleration in the future using the NVIDIA CUDA Toolkit together with the CuPy NumPy/SciPy-friendly library. On the other hand, two numerical frameworks can be used when computing laser propagation: a split-step Crank-Nicolson method applied to uncoupled time slices of the pulse (i.e., space-time phenomena are neglected), and a Fourier frequency decomposition for time slices, coupled with a Crank-Nicolson method for the spatial components acting on each slice.

Hint

We will not provide further details about the mathematical techniques employed, as they are covered in the Methods section. It suffices to say that the latter approach is more powerful and general because—just to give a preview—it allows the simulation of effects such as space-time focusing and self-steepening, which involve “mixing” spatial and temporal coordinates. Any realistic filamentation study should take these effects into account.

Returning to the example.toml file, the backend option is specified by the key computing_backend, and the propagation technique is selected using the key propagation_solver. The available values correspond to the two numerical frameworks: the split-step Crank-Nicolson solver, denoted by SSCN, and the Fourier-Crank-Nicolson solver, denoted by FCN. These are shown below:

propagation_solver = "FCN"   # "FCN" | "SSCN"
computing_backend = "CPU"    # "CPU" | "GPU" (not supported yet!)

Computational domain

Since acherus simulates laser beam propagation in free space using a rectangular grid of discrete points (or nodes), the numerical domain containing the electromagnetic wave packet and the medium stores values at these nodes in both space and time. This discretization corresponds to a finite-difference scheme—see the Methods section for details.

Mesh

Hence, withing the scope of example.toml, the user must specify the basic parameters that define the discretization of the radial, axial and temporal domains using the sections [medium_parameters.<option>], where <option> refers to the three discretized dimensions of the grid: space for the radial/transverse coordinate (denoted by r), axis for the axial/longitudinal coordinate (denoted by z), and time for the temporal coordinate (denoted by t). Each dimension is uniquely defined by the number of nodes and the pair of initial and final coordinates.

An example of the complete set of input parameters is shown below:

# Example of mesh discretization options
# Recall that physical magnitudes use SI units, unless otherwise stated
[grid_parameters.space] # Radial mesh section
nodes = 15001 # Number of radial nodes
space_min = 0.0 # Initial radial coordinate
space_max = 15e-3 # Final radial coordinate

[grid_parameters.axis] # Axial mesh section
nodes = 6001 # Number of propagation nodes
axis_min = 0.0 # Initial propagation coordinate
axis_max = 3.0 # Final propagation coordinate
snapshots = 5 # Number of saved propagation slices

[grid_parameters.time] # Temporal mesh section
nodes = 512 # Number of time nodes
time_min = -6e-12 # Initial time coordinate
time_max = 6e-12 # Final time coordinate

Note that the initial radial and axial coordinates must always be set to zero, and non-negative values must be used for their final coordinates. This is because a cylindrically symmetric coordinate system is enforced, and the initial laser pulse (or “driver” beam) begins propagating at the z-origin (set to zero), where the entrance to the medium is assumed to be located.

The user must assign an integer value to the snapshots key to record full radial and temporal simulation data at evenly spaced positions along the axial coordinates.

Note

The pulse propagation equation used in acherus —see the Physics section for a detailed account—belongs to the class of z-propagated equations. In practice, this means the user must decide how many “frozen” states of the simulation along the axial direction to store for later analysis and visualization. For example, setting snapshots = 5 will save simulation data (e.g., for plasma electron density) at six equally spaced z-slices, including the initial state.

Naturally, the number of grid points strongly affects both the simulation runtime and the memory requirements. For best performance, the number of time nodes should be chosen as a power of two (e.g., 256, 512, 1024, …), since the FFT algorithm used to decompose the laser wave packet into frequency modes is more efficient in such cases. The stronger the nonlinear interaction expected between the pulse and the medium during propagation, the more grid points will be necessary to resolve fine spatiotemporal details. Consequently, both execution time and memory requirements will increase further.

Tip

An important remark regarding the radial and temporal final coordinates is that they must be chosen large enough to ensure that the laser electric field envelope decays to zero near the boundaries, thereby avoiding artificial reflections caused by boundary conditions. A practical rule of thumb is to choose the radial length to be five times the initial beam waist of the pulse, and the temporal window size ten times the initial pulse duration. Ultimately, the domain size and the grid resolution are closely tied to each specific scenario, and should be carefully tested multiple times.

Perfectly Matched Layer

In some cases, adding boundary layers near the domain edges—where the fields are expected to vanish—is important to minimize reflections at the boundaries of the numerical domain. These artifacts can be difficult (and computationally expensive) to mitigate simply by enlarging the simulation domain. The example.toml includes an optional Perfectly Matched Layer (PML) applied to the radial coordinates. The layer is designed to attenuate the laser’s electric field as it enters the PML without introducing artificial reflections at the interface between the “physical” region and the PML, ideally reducing the reflection coefficient at the boundary of the computational domain to zero.

Fortunately, this type of boundary layers has been shown to work quite well for laser filamentation and beam propagation simulations. A detailed account is provided in the Methods section, following the approaches of Zheng et al. and Antoine et al. As a brief preview, an absorbing parabolic (quadratic) profile is used; it is continuous at the interface between the PML and the physical region and increases from zero up to a maximum absorption value.

If the user wishes to implement a PML layer, the keys for the absorption factor pml_damping and the PML thickness pml_width must be given two positive non-negative values. The pml_width parameter should be given as the ratio of the PML thickness to the total radial domain length, which consists of the physical domain (where the propagation equation remains unchanged) plus the PML layer. For example, if the total radial domain length is set to space_max = 10e-3 (in meters) and the PML thickness is chosen to be 10% of computational domain, setting pml_width = 0.1 yields a physical domain of 9e-3 and a PML thickness of 1e-3 for the radial grid.

# Example of PML
[grid_parameters.pml]
pml_damping = 10.0  # PML maximum damping coefficient (has no units)
pml_width = 0.1     # PML thickness (has no units)

Medium properties

The medium plays a central role in filamentation problems because it directly affects the balance between the competing physical mechanisms that reshape the spatiotemporal profile of the laser pulse during propagation. In particular, it determines how the beam self-focuses, defocuses, and loses energy during propagation. Even seemingly small changes in some of these parameters can lead to significantly different outcomes, making their accurate specification essential for reliable simulations.

Basic settings

To set the basic medium parameters in example.toml, the section header [grid_parameters.<option>] is used. Here, <option> must be a string from the set of transparent media names included in acherus: air, water, and silica (more could be added in the future). The medium choice does not affect the internal behavior of the <key>-<value> pairs within the section, but rather the dispersion and strong field ionization models employed for light-matter interactions. Here is the complete set of options available, normally used for air lasing:

# Example of air properties
[medium_parameters.AIR]
nonlinear_index = 3.0e-23   # Kerr index
energy_gap = 12.063         # ionization energy (in eV)
collision_time = 3.5e-13    # electron collision time
neutral_density = 5.4e24    # medium neutral atom density
initial_density = 1e9       # initial electron density
# recombination_rate = 1e-20      # Optional: electron recombination rate (default: None)
raman_partition = 0.5             # Optional: partition parameter (default: None)
raman_response_time = 70e-15      # Optional: damping time (default: None)
raman_rotational_time = 62.5e-15  # Optional: fundamental time (default: None)

Details about where each different physical magnitude participates should be consulted in the Physics section. The initial_desity parameter key represents the initial electron density at time_min (it should be negligible compared with neutral_density), and its purpose is to avoid near-zero logarithmic representation issues by introducing a small background ionization in the neutral medium. The key option for the electron-ion recombination rate is optional, as are the options related to stimulated molecular Raman scattering during propagation. This allows the user to include them or not, depending on the nature of the problem. Furthermore, not including them reduces simulation runtime, mainly because it avoids solving the Raman-Kerr contribution at each propagation step.

Hint

Recombination time scales are considerably longer (nanoseconds) than electron momentum transfer (collision) times and photoionization time scales (femtoseconds) for ultrashort pulses. This means recombination events occurs on much longer time scales than those considered in the vast majority of laser filamentation cases. On the other hand, the delayed (molecular) response of water (which red-shifts the spectrum of the pulse) has not been observed yet.

Dispersion models

Chromatic dispersion and wave diffraction are the two linear effects governing laser filamentation. These effects dominate spatiotemporal regions of low beam intensity, where nonlinear interactions vanish, and modulate the balance between nonlinear processes elsewhere.

In example.toml, dispersion is configured via the [dispersion.<option>] section. Users can choose between modeling full chromatic dispersion using the full option or approximating it with a finite number of dispersive coefficients (from one to four) using the partial option.

Danger

Care should be taken with the wavelength validity ranges of the dispersion models. Ensure that all frequencies involved during propagation remain within the range of the empirical equations.

In the full-dispersion case, quantities such as the pulse wavenumber and linear refractive index are computed from the dispersion relation derived from the semi-empirical Sellmeier equation for each medium; no additional parameters are required. Air uses Peck, water uses Mielenz, and silica uses Malitson; these are the most common models for laser filamentation.

In contrast, the truncated case requires the coefficients of the Taylor expansion of the dispersion relation around the central laser frequency, ranging from group velocity dispersion (GVD) to up to three higher-order chromatic terms. For further details, see the Physics section. Here are both scenarios:

# Example of full chromatic dispersion
[dispersion.full]

# Example of third order dispersion (in air for 800 nm)
[dispersion.partial]
k2 = 2e-28      # Required: 2nd order (GVD) dispersion coefficient
# k3 = 3e-43    # Optional: 3rd order dispersion coefficient
# k4 = 1e-58    # Optional: 4th order dispersion coefficient
# k5 = 5e-74    # Optional: 5th order dispersion coefficient

Photoionization models

The medium chosen has an important influence on the strong-field interaction with the laser beam and on how it forms the filament. Intense laser fields can rapidly ionize the medium they traverse via a process known as photoionization (PI) or optical field ionization (OFI), which is a key nonlinear process during laser filamentation and the dominant mechanism for plasma generation, governing electron density evolution (ionization is dominated by the pulse duration time scales, and the shorter the pulse duration, the more it controls ionization over collisions and recombination).

Two models are currently implemented (tunnel ionization limit could be included in the future!): the multiphoton ionization (MPI) limit and the general Keldysh theory.

Hint

For example, air uses the Perelomov, Popov, and Terent’Ev (PPT) theory with subsequent Mishima contributions, while water and silica use the Keldysh theory for condensed dielectrics and solids. For the adventurous, check the original articles!

In example.toml, the models are configured via the [ionization_model.<option>] sections. Users can choose between:

• keldysh option. The general Keldysh theory of strong-field ionization. No parameters are required; optional parameters include a convergence parameter tolerance and a max_iterations threshold, which have default values set to ensure, in most cases, the series computation converges with good accuracy. A third optional parameter, reduced_mass, should be specified only for condensed/bulky materials; it represents, in electron mass units, the electron-hole reduced mass.

• mpi option. The multiphoton limit of the general Keldysh theory, which applies for lower peak intensities. The cross_section parameter, representing the multiphoton coefficient, is required.

In both cases, the ionization models in acherus use an interpolation object that maps pulse intensities to their corresponding ionization rates. Two additional optional parameters, intensity_range and num_points, can also be specified, representing the intensity range of the pulse and the number of interpolation points used in the interpolation table, respectively. For a quick overview of the physics, see the Physics section; for details about the construction of the interpolation table, see the Methods section.

Danger

Be aware the pulse intensities used in the interpolation table should be wide enough to include all physically relevant values, avoiding extrapolation far from the important spatiotemporal regions. The maximum intensity value usually does not pose a problem, since peak intensity values can be estimated beforehand for a given problem.

Here are both ionization example.toml settings:

# Example of general Keldysh model
[ionization_model.keldysh]
intensity_range = [1e-6, 1e18]  # Optional: interpolation interval (default: [1e-1, 1e18])
num_points = 200000             # Optional: interpolation grid size (default: 10000)
# tolerance = 1e-3              # Optional: series convergence tolerance (default: 1e-3)
# max_iterations = 250          # Optional: series max iterations (default: 250)
# reduced_mass = 0.5            # Optional: only for condensed or bulky media (such as water and silica)

# Example of MPI model (in air for 800 nm)
[ionization_model.mpi]
cross_section = 2.81e-128       # Required: Multiphoton ionization (MPI) coefficient
intensity_range = [1e-6, 1e18]  # Optional: interpolation interval (default: [1e-1, 1e18])
num_points = 200000             # Optional: interpolation grid size (default: 10000)

Input beam

The initial laser pulse wavepacket, or driver, is defined in example.toml under the [pulse_parameters.<option>] section. The gaussian option is currently the only available spatiotemporal profile, although additional beam profiles—such as ring-Airy, Bessel, and Laguerre-Gauss—are planned for future releases.

The input beam plays a key role in filamentation, as it sets the initial optical properties of the wavepacket and influences how the balance between nonlinear processes evolves during propagation.

Note

The input conditions in the medium can enhance or diminish the propagation dynamics of the pulse. From beam collapse to pulse-splitting events and multiphoton absorption losses, all of these physical phenomena—including plasma generation and the spatial and temporal distribution of the filament—can be significantly influenced by the driver’s shape, .

Gaussian beam

The gaussian option has four required <key>-<value> pairs that define the beam:

• wavelength: Central wavelength of the beam.

• waist: Beam waist, defined as the half-width at \(1/e\) of the radial envelope.

• duration: Pulse duration, defined as the half-width at \(1/e\) of the temporal envelope.

• energy: Total pulse energy.

Together, these parameters describe a flat-phase, standard Gaussian pulse (bell-shaped), which is the most common input used in laser filamentation simulations. This is because it resembles the (idealized) output of laboratory laser systems. Although it represents an ideal case, it provides a reliable starting point.

To include an initial phase—such as curved wavefronts from lens focusing or a temporal (quadratic) chirp—the user can use the optional parameters focal_length and chirp. A third optional key, gauss_order, allows the generation of super-Gaussian (flat-top) radial profiles, which can better mimic realistic laser sources with bright centers and dim edges. See the Physics section for more details on the available input beam models.

The example.toml input beam block looks like this:

# Example of regular lens-focused Gaussian picosecond pulse
[pulse_parameters.gaussian]
wavelength = 1032e-9  # Required
waist = 3.57e-3       # Required (half-width at 1/e or FWHM/sqrt(2*log(2)) waist)
duration = 1274e-15   # Required (half-width at 1/e or FWHM/sqrt(2*log(2)) duration)
energy = 0.1          # Required
focal_length = 2.0    # Optional (default: None)
# chirp = 0.890       # Optional (default: None)
# gauss_order = 3     # Optional (default: 2)

Density solver

Temporal evolution of the electron density generated during propagation (see the Physics section) is computed for each radial coordinate using one of four available options in the [density_solver.<options>] section. The recommended options are three variable-step Runge-Kutta methods—rk23, rk45, and dop853—which rely on SciPy’s function solve_ivp. These methods use different error-control algorithms to adapt the size of each time step. They have proven to be excellent for resolving plasma generation, and the user must specify the relative tolerance, rtol, and absolute tolerance, atol, to ensure that the relative error stays below the acceptable threshold. See SciPy’s documentation for details on the algorithms and the meaning of the tolerance parameters.

It is important to understand that atol controls the number of correct decimal places, while rtol the number of correct significant digits. The solver attempts to keep the local error estimate below the total sum atol + rtol * abs(y) for every time step. The absolute tolerance only matters when the density is close to zero. In any realistic filamentation scenario, the density is strictly increasing—recombination processes slightly reduce free electron density, but their contribution to overall plasma dynamics is negligible.

Tip

In ultrashort filamentation, electron density values typically reach 10¹⁶–10¹⁷ cm⁻³ in gases and 10¹⁸–10¹⁹ cm⁻³ in condensed media. In such cases, the relative tolerance dominates the local error at every propagation step. For example, setting the initial electron density to 10⁹ cm⁻³ (typical for pure gases) effectively renders the absolute tolerance irrelevant.

Therefore, the electron density may approach its initial value but does not fall below it, nor does it approach zero.

The complete list of available options is given below:

# Example of density solver adaptive-step options
[density_solver.rk23]
rtol = 1e-9    # Optional (default: 1e-3)
# atol = 1e-6  # Optional (default: 1e-6)

[density_solver.rk45]
rtol = 1e-9    # Optional (default: 1e-3)
# atol = 1e-6  # Optional (default: 1e-6)

[density_solver.dop853]
rtol = 1e-9    # Optional (default: 1e-3)
# atol = 1e-6  # Optional (default: 1e-6)

# Example of density solver fixed-step option
[density_solver.rk4]

Running a simulation

Once acherus is installed and the Python environment is ready (for example, by following the Installation Guide instructions), simulations can be executed directly from the command-line interface by passing the configuration file name (e.g., example.toml) to the package. Make sure the file is located in your working directory.

Alternatively, you can provide a relative or absolute path if the configuration file is located elsewhere.

Depending on how acherus was installed, use one of the following approaches:

Installed

acherus example.toml

or, to override the output data path:

acherus example.toml --output ./results/output_data_path

Cloned (module execution)

python -m acherus example.toml

or, to override the output data path:

python -m acherus example.toml --output ./results/output_data_path

Cloned (editable mode)

acherus example.toml

or, to override the output data path:

acherus example.toml --output ./results/output_data_path

Tip

A typical simulation may take from a few hours to days, depending on the spatial and temporal resolution needed. Running the process in the background is recommended so you can keep using the terminal.

By default, the simulation output data and figures are written to the directories defined in the configuration file. The optional --output argument allows you to override this location from the command-line.

Monitoring a simulation

To monitor a simulation during runtime, use:

acherus-monitoring --config example.toml

or, if running from the cloned repository:

python -m acherus.monitoring --config example.toml

During runtime, the simulation writes to a file called acherus_monitoring.h5, which can be used to track the peak intensity evolution. The monitoring tool reads this file and saves the latest recorded propagation step of the pulse intensity. This is particularly useful for long runs, as it allows you to inspect intermediate results without waiting for completion.

Displaying results

Once a simulation has finished, two additional files—acherus_diagnostics.h5 and acherus_snapshots.h5—are saved in the data directory. These can be saved in the path pointing to the figures directory set by the user and visualized using the plotting tool:

acherus-plotting --config example.toml --cli-options

or, if plotting from the cloned repository:

python -m acherus-plotting --config example.toml --cli-options

The plotting tool can use the configuration file to locate input/output paths, or these can be overwritten by passing them as command-line arguments to the plotting tool parser.

Plotting options

Any CLI arguments for the plotting tool can be used independently (unless stated otherwise). The following organization and examples are provided for clarity and completion purposes.

Path arguments

The path-related arguments for reading and writing input/output data are:

• --config: Path to the TOML configuration file. If defined, it uses the data and figure paths provided by the user.

• --sim-path: Path where data files are stored. Overrides the configuration file.

• --fig-path: Path where figures are saved. Overrides the configuration file.

Tip

It is recommended to define data and figure paths in the configuration file before running a simulation. Then, you only need to pass the configuration file (name and extension) to the plotting tool.

Variables and dimensions arguments

These arguments control what is plotted:

• --variables: Comma-separated list of physical quantities to plot (default: intensity,density,fluence,radius). Available options include:

  • intensity: Beam intensity (full space-time profiles, peak intensity, and on-axis intensity).

  • density: Electron density (full space-time profiles, peak density, and on-axis density).

  • fluence: Beam fluence distribution.

  • radius: Beam radius.

Example:

acherus-plotting --variables intensity,density

• --dimensions: Comma-separated list of dimensions to plot (default: 1d,2d). Available options include:

• 1d: One-dimensional plots (line plots over time or propagation distance).

• 2d: Two dimensional plots (color maps over spatial and temporal coordinates).

• 3d: Three-dimensional plots (surface plots over spatial and temporal coordinates).

Example:

acherus-plotting --dimensions 1d,2d

Domain arguments

To restrict the region of the computational domain:

• --radial-limit: Maximum radial coordinate (default: full grid).

• --axial-range: Axial range as min,max tuple. Use ="min,max" if values are negative (default: full grid).

• --time-range: Time range as min,max tuple. Use ="min,max" if values are negative (default: full grid).

• --scale: Axis scaling. Options are:

  • linear: Use regular axis (default).

  • log: Use logarithmic axis.

  • both: Use both regular and logarithmic axes (one plot each).

• --log-y-range: logarithmic range as min,max tuple. Applies to:

  • 1D semi-logarithmic plots with a logarithmic y-axis.

  • 2D semi-logarithmic plots with a logarithmic (colormap) y-axis.

  • 3D semi-logarithmic plots with a logarithmic z-axis. Required when using log or both.

• --log-rt-levels: Number of contour levels for 2D semi-logarithmic (r,t) plots. Required when using log or both. For example, specifying four contour levels displays a logarithmic scale (in normalized units) from 10⁰ to 10⁻⁴ using the selected colormap, with values out of range shown in white.

One example would be:

acherus-plotting --radial-limit 2e-3 --axial-range 1.2,2.2 --time-range="-1.5e-12,2.5e-12"

Visualization arguments

To control figure appearance:

• --radial-symmetry: Displays plots symmetrically around the radial axis. Accepts true or false (default: false).

• --colors-1d: Comma-separated triplet of RGB colors (0-1) for 1D plots (default: 0.121569,0.466667,0.705882).

• --colors-2d: Matplotlib colormap name for 2D/3D plots (default: jet). See the Matplotlib colormap reference for the options available.

• --dpi: Figure resolution in dots per inch (default: 300).

• --camera-view: Comma-separated triplet of viewing angles (azimuth,elevation,altitude) for 3D plots (default: 200,15,0).

An example would be:

acherus-plotting --dimension 1d,2d,3d --colors-1d 0.2,0.6,0.8 --colors-2d viridis --dpi 150 --camera-view 175,8,15 --radial-symmetry true

Air filamentation example

To illustrate a few scenarios, four example input .toml files are provided in the 📁 examples/ directory of the GitHub repository. These include femtosecond and picosecond filamentation in air at infrared wavelengths, as well as femtosecond filamentation in water at ultraviolet and infrared regimes. Each case shows distinctive nonlinear dynamics, and more examples are planned for future releases.

As a demonstration of the plotting tool’s features, consider the picosecond air filamentation case, which reproduces the experimental and numerical results from Houard et al. The corresponding configuration file is named 001_air_IR_ps.toml and can be found inside the 📁 examples/ folder.

To run the simulation process in the background (Linux or macOS), use:

nohup acherus 001_air_IR_ps.toml &

This command allows the process to continue even after closing the terminal. On most linux distributions, you can monitor process diagnostics by running top in your terminal, or one of its modern variants (which may need to be installed), such as htop or btop.

Note

The nohup prefix ensures that the simulation continues running after the terminal is closed, while & runs the command in the background. For example, this picosecond simulation (involving relatively long-duration pulses) takes about 35 hours to complete on an average gaming workstation. More modern CPUs should perform significantly faster. Running the process in the background is therefore strongly recommended.

To periodically monitor the evolution of the beam’s peak intensity along propagation, run:

acherus-monitoring --config 001_air_IR_ps.toml

After the simulation finishes, the user may wish to visualize, for example, the two-dimensional intensity profile and fluence distribution of the laser pulse within a truncated domain that highlights the most relevant features:

acherus-plotting \
--config 001_air_IR_ps.toml \
--variables intensity,fluence \
--dimensions 2d \
--axial-range 1.2,3.0 \
--time-range="-2.5e-12,2.5e-12" \
--radial-limit 1.5e-3 \
--radial-symmetry true

Note

The \ symbol is a line continuation character used for readability. It is not part of the command arguments, although it works as shown in most bash-like shell environments.

This set of CLI instructions produces five equidistant snapshots at different propagation distances, showing the radial and temporal intensity profiles. It also generates the on-axis spatiotemporal intensity profile, the spatial distribution of the peak intensity (for each local time coordinate), and the fluence distribution. An example of these last three outputs is shown below.

The top row displays the beam’s peak intensity across all radial coordinates along the propagation axis, as well as the on-axis spatiotemporal intensity profile. The bottom image shows the fluence distribution (energy per unit area) of the beam.

Readers already familiar with ultrashort laser filamentation can use these results to interpret the key—and sometimes subtle—physical processes that transform and distort the initial Gaussian pulse into the structures shown here. For further details, refer to the original work by Houard et al., from which most of the parameters for this picosecond simulation were taken.

For readers new to nonlinear optics and filamentation, see the Physics Guide for an introduction to the underlying physical concepts. This fascinating field has been actively studied for over six decades and offers a rich body of experimental and theoretical literature.

A recommended reference is the extensive review by Couairon and Mysyrowicz, which provides broad and in-depth coverage of femtosecond filamentation.

Note

As of 2026, this review was published nearly 20 years ago, illustrating how rich, diverse, and well-developed the field already was at that time. Today, many open questions remain, as some observed phenomena are still not fully understood. Researchers continue to propose new interpretations by examining these effects from different perspectives.

More detailed references on the equations, numerical methods, and implementation considerations can be found in works by Couairon et al. and Kolesik and Moloney, among others.