PICLas Documentation Logo
  • Code of Conduct
    • Our Pledge
    • Our Standards
    • Enforcement Responsibilities
    • Scope
    • Enforcement
    • Enforcement Guidelines
      • 1. Correction
      • 2. Warning
      • 3. Temporary Ban
      • 4. Permanent Ban
    • Attribution
  • Acknowledge PICLas
    • In presentations
    • Acknowledge Sentence
    • Citation

User Guide

  • Overview
  • 1. Installation
    • 1.1. AppImage executable download
    • 1.2. Prerequisites
      • 1.2.1. Ubuntu or similar
      • 1.2.2. CentOS
    • 1.3. Required Libraries
      • 1.3.1. Installing GCC
      • 1.3.2. Installing OpenMPI
      • 1.3.3. Installing HDF5
      • 1.3.4. Installing PETSc
    • 1.4. Obtaining the source
    • 1.5. Compiling the code
      • 1.5.1. Directory paths
  • 2. Mesh Generation
    • 2.1. Mesh generation with PyHOPE
    • 2.2. Mesh conversion with PyHOPE
      • 2.2.1. Mesh generation with Gmsh
      • 2.2.2. Mesh generation with Coreform Cubit
      • 2.2.3. Mesh generation with OMNIS/HEXPRESS
      • 2.2.4. Mesh generation with GridPro
      • 2.2.5. Mesh generation with CENTAUR
      • 2.2.6. Mesh generation with MeshGems/SALOME
  • 3. Workflow
    • 3.1. Compiler options
    • 3.2. Solver settings
    • 3.3. Setup of parameter file(s)
    • 3.4. Simulation
      • 3.4.1. Parallel execution
      • 3.4.2. Profile-guided optimization (PGO)
    • 3.5. Post-processing
  • 4. Features & Models
    • 4.1. Variable polynomial degree (p-adaption)
      • 4.1.1. Refining boundary elements (pAdaptionType = non-periodic-BC)
    • 4.2. Particle Tracking
      • 4.2.1. DoRefMapping
      • 4.2.2. Tracing
      • 4.2.3. Parameters for DoRefMapping and Tracing (NEEDS UPDATING)
      • 4.2.4. Rotating Frame of Reference
        • 4.2.4.1. Time step subcycling for rotating frame of reference
      • 4.2.5. Cartesian background mesh (Fast Initialization Background Mesh, FIBGM)
    • 4.3. Field Solver - Poisson Equation
      • 4.3.1. PETSc Solver
      • 4.3.2. Internal CG Solver
      • 4.3.3. Symmetric Simulations
    • 4.4. Boundary Conditions - Field Solver
      • 4.4.1. Maxwell’s Equations
      • 4.4.2. Poisson’s Equation
        • 4.4.2.1. RefState boundaries
        • 4.4.2.2. Linear potential function
        • 4.4.2.3. Floating boundary condition (FPC)
        • 4.4.2.4. Distributed capacitance boundary condition (DCBC)
        • 4.4.2.5. Circuit model boundary condition (CMBC)
        • 4.4.2.6. Electric potential condition (EPC)
        • 4.4.2.7. Power control
        • 4.4.2.8. Zero potential enforcement
        • 4.4.2.9. Bias Voltage DC
        • 4.4.2.10. Bias Voltage AC
        • 4.4.2.11. Bias Voltage AC and Fixed coupled power
        • 4.4.2.12. Fixed/constant bias voltage and AC
      • 4.4.3. Dielectric Materials
        • 4.4.3.1. Dielectric Zones
    • 4.5. Boundary Conditions - Particle Solver
      • 4.5.1. Reflective Wall
        • 4.5.1.1. Wall movement (Linear & rotational)
        • 4.5.1.2. Linear temperature gradient
        • 4.5.1.3. Radiative equilibrium
      • 4.5.2. Rotational Periodicity
        • 4.5.2.1. Intermediate Plane Definition
      • 4.5.3. Porous Wall / Pump
      • 4.5.4. Surface Chemistry
        • 4.5.4.1. Empirical model for a sticking coefficient
        • 4.5.4.2. Fixed probability surface chemistry
        • 4.5.4.3. Secondary Electron Emission (SEE)
      • 4.5.5. Catalytic Surfaces
        • 4.5.5.1. Adsorption
        • 4.5.5.2. Desorption
        • 4.5.5.3. Catalytic Reaction
      • 4.5.6. Deposition of Charges on resolved Dielectric Surfaces
      • 4.5.7. Deposition of charges on distributed capacitance boundary condition (DCBC) surfaces
    • 4.6. Particle Initialization & Emission
      • 4.6.1. Species Type (InteractionID)
      • 4.6.2. Velocity Distribution Functions
        • 4.6.2.1. Cosine distribution
        • 4.6.2.2. Double cosine distribution
      • 4.6.3. Initialization Regions
        • 4.6.3.1. Cell local
        • 4.6.3.2. Point
        • 4.6.3.3. Circular Disc
        • 4.6.3.4. Cuboid
        • 4.6.3.5. Cylinder
        • 4.6.3.6. Sphere
        • 4.6.3.7. Photo-ionization
        • 4.6.3.8. Emission Distribution
        • 4.6.3.9. PIC Neutralization Boundaries (neutral outflow condition)
        • 4.6.3.10. Polychromatic Photo-ionization
        • 4.6.3.11. Initial Ionization
      • 4.6.4. Emission at Boundaries (Surface Flux)
        • 4.6.4.1. Emission Current & Mass Flow
        • 4.6.4.2. Thermionic Emission (including Schottky effect)
        • 4.6.4.3. Circular/Racetrack Inflow
        • 4.6.4.4. Adaptive/Subsonic Boundaries
        • 4.6.4.5. Verification
        • 4.6.4.6. Missing descriptions
    • 4.7. Particle-In-Cell
      • 4.7.1. Lorentz force
      • 4.7.2. Charge and Current Deposition
        • 4.7.2.1. Linear Distribution Over Cell Interfaces
        • 4.7.2.2. Shape Function
        • 4.7.2.3. Compatibility with Field Solver Symmetry Settings
    • 4.8. Drift-diffusion model
      • 4.8.1. Finite volume solver
      • 4.8.2. Boundary conditions
      • 4.8.3. Plasma chemistry
      • 4.8.4. Visualisation
    • 4.9. Magnetic Background Field
      • 4.9.1. Read-in of an External Field
      • 4.9.2. Calculation with superB
        • 4.9.2.1. Magnetic Field by Permanent Magnets
        • 4.9.2.2. Magnetic Field by Coils
        • 4.9.2.3. Time-dependent Magnetic Coils
    • 4.10. Direct Simulation Monte Carlo
      • 4.10.1. Species Definition
      • 4.10.2. Pairing & Collision Modelling
        • 4.10.2.1. Cross-section based collision probabilities
      • 4.10.3. Inelastic Collisions & Relaxation
        • 4.10.3.1. Rotational Relaxation
        • 4.10.3.2. Vibrational Relaxation
        • 4.10.3.3. Electronic Relaxation
      • 4.10.4. Chemistry & Ionization
        • 4.10.4.1. Total Collision Energy (TCE)
        • 4.10.4.2. Quantum Kinetic Chemistry (QK)
        • 4.10.4.3. Cross-section Chemistry (XSec)
        • 4.10.4.4. Backward Reaction Rates
      • 4.10.5. Granular Flows
        • 4.10.5.1. Defining Granular Flows
        • 4.10.5.2. Gravitational Effects
        • 4.10.5.3. Granular-Wall Interactions
        • 4.10.5.4. Granular Species Interaction with Background Gas Distribution
        • 4.10.5.5. Verification of One-Way Coupling
      • 4.10.6. Additional Features
        • 4.10.6.1. Deletion of Chemistry Products
        • 4.10.6.2. Ambipolar Diffusion
      • 4.10.7. Ensuring Physical Simulation Results
    • 4.11. Background Gas
      • 4.11.1. Distribution from DSMC result
      • 4.11.2. Regions
      • 4.11.3. Trace species
      • 4.11.4. Cross-section based collision probability
      • 4.11.5. Cross-section based vibrational relaxation probability
      • 4.11.6. Cross-section based electronic relaxation probability
    • 4.12. Unified Species Database
      • 4.12.1. Species data
      • 4.12.2. Reaction data
      • 4.12.3. Cross-section data
    • 4.13. Fokker-Planck Collision Operator
    • 4.14. Bhatnagar-Gross-Krook Collision Operator
    • 4.15. Features of the Particle Solver
      • 4.15.1. Macroscopic Restart
      • 4.15.2. Variable Time Step
        • 4.15.2.1. Distribution
        • 4.15.2.2. Linear scaling
        • 4.15.2.3. Species-specific time step
      • 4.15.3. Symmetric Simulations
        • 4.15.3.1. 1D Simulations
        • 4.15.3.2. 2D/Axisymmetric Simulations
      • 4.15.4. Variable Particle Weighting
        • 4.15.4.1. Linear Weighting in 3D
        • 4.15.4.2. Cell-local Weighting
        • 4.15.4.3. Split-And-Merge
      • 4.15.5. Virtual Cell Merge
    • 4.16. Radiation & Radiation Transport
    • 4.17. Raytracing & Photoionization
      • 4.17.1. Pulse definition
      • 4.17.2. Surface interaction
      • 4.17.3. Photo-ionization probability
      • 4.17.4. Volume and surface super-sampling
    • 4.18. Discrete velocity method
      • 4.18.1. Finite volume solver
      • 4.18.2. Initial and boundary conditions
      • 4.18.3. Visualisation
  • 5. Visualization & Output
    • 5.1. Particle Data
    • 5.2. Field Solver and PIC
      • 5.2.1. Element-polynomial field properties
      • 5.2.2. Element-constant field/particle properties
      • 5.2.3. Time-averaged Fields
    • 5.3. Particle Flow and Surface Sampling
      • 5.3.1. Electronic excitation
    • 5.4. Integral Variables
      • 5.4.1. Field Variables
      • 5.4.2. Particle Variables
      • 5.4.3. Surface Variables
    • 5.5. Dynamic Mode Decomposition
      • 5.5.1. Ritz spectrum (coaxial_DMD_Spec.dat)
      • 5.5.2. Mode visualization (coaxial_DMD.h5)
    • 5.6. Surface Group Output
  • 6. Tools
    • 6.1. Unified Species Database (USD)
      • 6.1.1. Maintain and edit database
        • 6.1.1.1. Species parameters
        • 6.1.1.2. Chemical reactions
        • 6.1.1.3. Collision cross-sections
        • 6.1.1.4. Surface chemistry
        • 6.1.1.5. Diffusion coefficients
    • 6.2. Userblock
      • 6.2.1. extract_userblock.py
      • 6.2.2. rebuild.py
  • 7. Tutorials
    • 7.1. Plasma Wave (PIC, Poisson’s Equation)
      • 7.1.1. Mesh Generation with PyHOPE (pre-processing)
      • 7.1.2. PIC Simulation with PICLas
        • 7.1.2.1. General numerical setup
        • 7.1.2.2. Boundary conditions
        • 7.1.2.3. Field solver
        • 7.1.2.4. Particle solver
        • 7.1.2.5. Analysis setup
        • 7.1.2.6. Running the code
      • 7.1.3. Visualization (post-processing)
    • 7.2. Landau Damping (PIC, Poisson’s Equation)
      • 7.2.1. Mesh Generation with PyHOPE (pre-processing)
      • 7.2.2. PIC Simulation with PICLas
        • 7.2.2.1. Numerical Setup
        • 7.2.2.2. Running the code
      • 7.2.3. Visualisation (post-processing)
    • 7.3. Two Stream Instability (PIC, Poisson’s Equation)
      • 7.3.1. Mesh Generation with PyHOPE (pre-processing)
      • 7.3.2. PIC Simulation with PICLas
        • 7.3.2.1. Overview
        • 7.3.2.2. Numerical setup
        • 7.3.2.3. Running the code
      • 7.3.3. Visualization (post-processing)
    • 7.4. Negative Streamer Discharge (PIC, Poisson’s Equation)
      • 7.4.1. Drift-Diffusion Electron Fluid
        • 7.4.1.1. Mesh Generation with PyHOPE (pre-processing)-1
        • 7.4.1.2. Simulation with PICLas-1
        • 7.4.1.3. Visualization (post-processing)-1
      • 7.4.2. Particle-in-cell/Monte Carlo Collision (PIC/MCC)
        • 7.4.2.1. Mesh Generation with PyHOPE (pre-processing)-2
        • 7.4.2.2. Simulation with PICLas-2
        • 7.4.2.3. Visualization (post-processing)-2
        • 7.4.2.4. Cross-section Database
      • 7.4.3. Comparison of Electron Fluid and PIC-MCC
    • 7.5. Adiabatic Box/Reservoir (DSMC, Relaxation/Chemistry)
      • 7.5.1. Mesh Generation with PyHOPE (pre-processing)
      • 7.5.2. Simulation: Chemistry disabled
        • 7.5.2.1. General numerical setup
        • 7.5.2.2. Analysis setup
        • 7.5.2.3. Boundary conditions
        • 7.5.2.4. Particle solver
        • 7.5.2.5. DSMC setup
        • 7.5.2.6. Running the code without chemical reactions (single-core execution)
      • 7.5.3. Visualization, chemistry disabled (post-processing)
      • 7.5.4. Simulation: Chemistry enabled
        • 7.5.4.1. Reactions
        • 7.5.4.2. Running the code with chemical reactions (Parallel computing)
      • 7.5.5. Visualization, chemistry enabled (post-processing)
    • 7.6. Hypersonic Flow around the 70° Cone (DSMC) - 2D Mesh
      • 7.6.1. Mesh Generation with PyHOPE (pre-processing)
        • 7.6.1.1. Mesh generated by HEXPRESS (CGNS format)
        • 7.6.1.2. Mesh generated by Gmsh (msh format)
      • 7.6.2. Flow simulation with DSMC
        • 7.6.2.1. Exploiting symmetry
        • 7.6.2.2. Octree
        • 7.6.2.3. Sampling
      • 7.6.3. Run the simulation
        • 7.6.3.1. MPI and Load Balancing
      • 7.6.4. Visualization (post-processing)
        • 7.6.4.1. Ensuring physical simulation results
        • 7.6.4.2. Visualizing flow field variables (DSMCState)
        • 7.6.4.3. Visualizing surface variables (DSMCSurfState)
    • 7.7. Hypersonic Flow around the 70° Cone (DSMC) - 3D Mesh with Gmsh
      • 7.7.1. Mesh generation with Gmsh
        • 7.7.1.1. .geo mesh file creation
        • 7.7.1.2. .msh mesh file creation
        • 7.7.1.3. .h5 mesh file creation
      • 7.7.2. Flow simulation with DSMC
        • 7.7.2.1. Short simulation run
        • 7.7.2.2. Long simulation run
  • 8. Cluster Guidelines
    • 8.1. Simulating at HLRS
      • 8.1.1. Cloning with the SSH protocol
        • 8.1.1.1. Method 1 (Proxy Jump)
        • 8.1.1.2. Method 2 (Remote Forwarding)
      • 8.1.2. Setting up the module environment
        • 8.1.2.1. Setup for Vulcan
        • 8.1.2.2. Setup for Hunter (CPU only)
      • 8.1.3. Installing PETSc with restricted internet access
        • 8.1.3.1. Configure for Vulcan
        • 8.1.3.2. Configure for Hunter
      • 8.1.4. Compiling and executing PICLas
      • 8.1.5. Lustre striping
      • 8.1.6. Species-zero bug
  • 9. Appendix
    • 9.1. Tested compiler combinations
    • 9.2. Unified Species Database (USD)
      • 9.2.1. Electronic database
      • 9.2.2. Reactions
  • References

Developer Guide

  • Overview
  • 1. Development Workflow
    • 1.1. Issues & Milestones
    • 1.2. Merge Request (MR)
      • 1.2.1. Automatic release note generation
  • 2. Style Guide
    • 2.1. File Header
    • 2.2. Header of Functions and Subroutines
    • 2.3. Variables
    • 2.4. Functions and Control Structures
    • 2.5. Workflow Description
    • 2.6. Special Rules
      • 2.6.1. CALL Allocate_Shared()
      • 2.6.2. USE MOD_Preproc
    • 2.7. Code Annotations
  • 3. Linting
    • 3.1. Fortitude (Fortran)
      • 3.1.1. Fortitude pre-commit hook
      • 3.1.2. Fixing Fortitude violations
    • 3.2. Ruff (Python)
      • 3.2.1. Ruff pre-commit hook
      • 3.2.2. Fixing Ruff violations
    • 3.3. Finding earlier fixes
    • 3.4. Separate commits
  • 4. Code Extension
    • 4.1. Surface Sampling & Output
    • 4.2. Allocating particle data
    • 4.3. Insert new particles
    • 4.4. Remove particles
    • 4.5. Particle internal data container
      • 4.5.1. MPI communication
    • 4.6. Useful Functions
      • 4.6.1. General Functions and Subroutines
      • 4.6.2. Particle Functions and Subroutines
    • 4.7. CollectiveStop
  • 5. Writing Documentation
    • 5.1. Building documentation
      • 5.1.1. HTML Version
      • 5.1.2. PDF Version
    • 5.2. Writing guidelines
      • 5.2.1. Figures
  • 6. Release & Deployment
    • 6.1. Release Procedure
      • 6.1.1. Release Tag
      • 6.1.2. GitHub
    • 6.2. Automatic Deployment to GitHub
    • 6.3. AppImage Executable
      • 6.3.1. piclas
      • 6.3.2. piclas2vtk and other tools
      • 6.3.3. Troubleshooting
  • 7. MPI Implementation
    • 7.1. General Rules
    • 7.2. Shared Memory Windows
    • 7.3. Debugging MPI
    • 7.4. Construction of Halo Region (MPI 3.0 Shared Memory)
      • 7.4.1. Mesh Geometry
        • 7.4.1.1. ElemInfo
        • 7.4.1.2. SideInfo
        • 7.4.1.3. NodeInfo
      • 7.4.2. Element/Side Mappings
        • 7.4.2.1. SurfSide
      • 7.4.3. Particle Element Mappings
    • 7.5. Custom communicators
      • 7.5.1. Available communicators
        • 7.5.1.1. Feature-specific
        • 7.5.1.2. Flexi-specific
  • 8. Regression Testing
    • 8.1. reggie Tool
    • 8.2. Local execution of reggie
    • 8.3. Compression of HDF5 reference files
    • 8.4. Running GitLab .gitlab-ci.yml Tests
    • 8.5. Remote Testing on Gitlab
    • 8.6. Code Coverage
      • 8.6.1. Coverage on GitLab
        • 8.6.1.1. Inspecting data on GitLab
        • 8.6.1.2. Inspecting data locally
      • 8.6.2. Local coverage tests
        • 8.6.2.1. Combining single reports
      • 8.6.3. Reggie coverage
    • 8.7. Local Testing using gitlab-ci-local
      • 8.7.1. Example
  • 9. Unit tests
    • 9.1. Integration of unit test with CTest
    • 9.2. Implementation of unit tests
      • 9.2.1. CMakeLists.txt
      • 9.2.2. General unit test structure
      • 9.2.3. Generation of reference mesh data
  • 10. Troubleshooting
    • 10.1. WriteArrayToHDF5() and the collective flag
    • 10.2. Seemingly meaningless change in code triggers segmentation fault or slow down of the code
    • 10.3. Possible memory leak detection when using MPICH
      • 10.3.1. PETSc
    • 10.4. Compiler Options
    • 10.5. Maximum Number of Warnings
  • 11. Performance Analysis
    • 11.1. Extrae and Paraver
      • 11.1.1. Installation
      • 11.1.2. Code Instrumentation
      • 11.1.3. Tracing the code
        • 11.1.3.1. Load the required Modules
        • 11.1.3.2. Create tracing.sh and extrae.xml in the simulation directory
      • 11.1.4. User functions
        • 11.1.4.1. Run the application
        • 11.1.4.2. Convert the Extrae output for Paraver
        • 11.1.4.3. Analysing the results with Paraver
    • 11.2. Intel® VTune™
      • 11.2.1. VTune Installation
      • 11.2.2. Batch jobs
      • 11.2.3. Usage
    • 11.3. Valgrind
      • 11.3.1. Installation of Valgrind
      • 11.3.2. Execution of Valgrind
        • 11.3.2.1. Callgrind
        • 11.3.2.2. Memcheck
        • 11.3.2.3. Massif
        • 11.3.2.4. DHAT
PICLas Documentation
  • 4. Features & Models
  • View page source

4. Features & Models

Table of Contents

  • 4.1. Variable polynomial degree (p-adaption)
  • 4.2. Particle Tracking
  • 4.3. Field Solver - Poisson Equation
  • 4.4. Boundary Conditions - Field Solver
  • 4.5. Boundary Conditions - Particle Solver
  • 4.6. Particle Initialization & Emission
  • 4.7. Particle-In-Cell
  • 4.8. Drift-diffusion model
  • 4.9. Magnetic Background Field
  • 4.10. Direct Simulation Monte Carlo
  • 4.11. Background Gas
  • 4.12. Unified Species Database
  • 4.13. Fokker-Planck Collision Operator
  • 4.14. Bhatnagar-Gross-Krook Collision Operator
  • 4.15. Features of the Particle Solver
  • 4.16. Radiation & Radiation Transport
  • 4.17. Raytracing & Photoionization
  • 4.18. Discrete velocity method

The goal of PICLas is to enable to approximation of the complete Boltzmann equation:

\[ \frac{\partial f}{\partial t} + \mathbf{v}\cdot\frac{\partial f}{\partial \mathbf{x}} + \frac{\mathbf{F}}{m}\cdot\frac{\partial f}{\partial \mathbf{v}} = \left.\frac{\partial f}{\partial t}\right|_{\mathrm{coll}} \]
Previous Next

© Copyright 2026 PICLas Developers.

Built with Sphinx using a theme provided by Read the Docs.