User Quick Start

中文 English

使用者快速入门

这条路线面向“只想调用 AlgoPlasma 子程序”的使用者。目标很简单：拿到源码，跑通一个小测试，然后在自己的程序里调用一个子程序。

获取源码 跑 A01 测试 看调用方式 编译自己的程序

完成标准

• tests/002_pusher/A01_Boris_3Dxyz 能编译并运行。

• 能调用 sub_A01_Boris_3Dxyz(v, E, B, k)。

• 知道 PIC 流程中每一步大致该查哪个 AlgoPlasma 模块。

1. 获取源码

AlgoPlasma 目前主要是源码级算法库，不需要先打包安装。最简单的“安装”就是把源码仓库放在本机，并在编译时开启 C 预处理。

git clone <repo-url> algoplasma
cd algoplasma

2. 跑一个最小测试

先跑 A01 的 Boris 推进器测试。它依赖少，适合确认本机编译器和基本环境。

cd tests/002_pusher/A01_Boris_3Dxyz
./clean.sh
./make.sh
./run.sh

如果 build/case*.dat 生成了，就说明这个最小测试跑通。想看轨道图时再运行：

./plot.sh

这个测试的详细说明见 A01_Boris_3Dxyz 测试。

3. 调用一个子程序

调用 AlgoPlasma 的基本方式是：在自己的 Fortran 程序里 #include 对应的 mod_*.f90，然后 use 这个 module。

#include "A_Pusher/A01_Boris_3Dxyz/mod_A01_Boris_3Dxyz.f90"

program demo_a01
    use mod_A01_Boris_3Dxyz
    implicit none

    real :: v(3), E(3), B(3), k

    v = (/1.0, 0.0, 0.0/)
    E = 0.0
    B = (/0.0, 0.0, 1.0/)
    k = 0.01

    call sub_A01_Boris_3Dxyz(v, E, B, k)
end program demo_a01

在仓库根目录编译这个例子最省事：

gfortran -cpp -O2 -fdefault-real-8 demo_a01.f90

注意：当前不少 Fortran 程序直接使用默认 real。如果希望按双精度运行，需要在编译命令中加入对应选项，例如 gfortran -fdefault-real-8；使用 Intel Fortran 时可用类似 ifx -real-size 64 的选项。测试目录里的 make.sh 若已经包含该选项，直接按脚本运行即可。

4. PIC 流程里该用哪些模块

AlgoPlasma 不是一个固定的 PIC 主程序，而是一组可以拼到自己程序里的算法模块和子程序。一个常见 PIC 程序可以按下面的流程理解：

PIC 流程与 AlgoPlasma 模块对应关系。

对应到 AlgoPlasma，可以先按这个表找模块：

PIC 步骤	AlgoPlasma 模块	常见子程序组
初始化粒子和读取初值	I_Initializer，F_IO	I01_par_distribute，I02_par_init_and_load，F01_par_load，F03_field_load
网格场插值到粒子	C_Gather	C01_gather_3Dxyz，C02_gather_3Dxyz_bspline
推进粒子	A_Pusher	A01_Boris_3Dxyz，A02_Boris_3Drtz，A03_Higuera_Cary_relativistic_3Dxyz
碰撞	G_Collision	G01_MCC，G02_MCC_network
粒子沉积到网格	B_Scatter	B01_scatter_3Dxyz，B02_deposit_3d_cyl
场求解或场推进	D_Poisson，E_Maxwell	D01-D04 Poisson/HYPRE 求解器，E01-E03 FDTD/CPML
MPI 边界和粒子交换	H_MPI_Exchange	H01_mpi_exchange_field，H02_mpi_exchange_par，H03_mpi_exchange_den
输出粒子和场	F_IO	F02_par_output，F04_field_output

静电 PIC 通常更关注 B_Scatter 得到电荷密度，然后用 D_Poisson 求电势或电场。电磁 PIC 通常还会沉积电流，并用 E_Maxwell 更新电磁场。并行程序里，H_MPI_Exchange 可能会在场更新、沉积后、粒子跨区后分别出现。

学习碰撞：从 G02 零维算例开始

G02 的小算例能直接看到“一群热粒子怎样被较冷的气体逐渐冷却”。 零维表示忽略空间差异，粒子仍有三个方向的速度。只需要速度、动能和平均数的基础。 从仓库根目录运行：

bash tests/009_collision/G02_MCC_network/examples/collision_box/run.sh

这个脚本自行构建，需要 CMake 3.20 或以上、C/C++ 编译器（C++20）， 绘图需要 Python 3 和 Matplotlib；默认无需 Fortran 或 MPI。 看到 collision_box: PASS 后，在算例的 results/ 中查看图片和 checks.csv。 碰撞盒入门教程 解释每张图与通过判据。 数据是合成值，只用于软件验证。

G02 的 Fortran 接口需要链接它的 C++ 库，接入方式见 G02 模块页。

后续调用其他模块

• 先看模块目录里的 README.zh-CN.md。

• 再看对应测试页，确认运行命令和输出含义。

• 复杂模块可能需要 MPI、HYPRE、HDF5 或 Python 绘图环境，具体以模块说明为准。

常见卡点

• run.sh 报找不到 build：先运行 ./make.sh。

• make.sh 编译失败：先确认本机有 gfortran，并从测试目录运行脚本。

• plot.sh 失败：不影响调用 AlgoPlasma，先确认 build/case*.dat 已生成。

• include 路径找不到：优先从仓库根目录编译，或把 include 路径改成相对当前编译目录的路径。

User Quick Start

This route is for users who only want to call AlgoPlasma routines. The goal is simple: get the source tree, run one small test, then call one subroutine from your own program.

Get source Run A01 test Read call pattern Compile your program

The First Pass Is Done When

• tests/002_pusher/A01_Boris_3Dxyz builds and runs.

• You can call sub_A01_Boris_3Dxyz(v, E, B, k).

• You know which AlgoPlasma module to check for each main PIC step.

1. Get The Source Tree

AlgoPlasma is currently a source-level algorithm library. The simplest installation is to keep the source tree locally and compile callers with C preprocessing enabled.

git clone <repo-url> algoplasma
cd algoplasma

2. Run One Minimal Test

Start with the A01 Boris pusher test. It has few dependencies and is a good way to confirm that the compiler and basic environment work.

cd tests/002_pusher/A01_Boris_3Dxyz
./clean.sh
./make.sh
./run.sh

If build/case*.dat is generated, the minimal test has passed. Run the plotting step only when you want figures:

./plot.sh

See A01_Boris_3Dxyz Test for the full test notes.

3. Call One Subroutine

The basic call pattern is to #include the target mod_*.f90 file, then use the module in your Fortran program.

#include "A_Pusher/A01_Boris_3Dxyz/mod_A01_Boris_3Dxyz.f90"

program demo_a01
    use mod_A01_Boris_3Dxyz
    implicit none

    real :: v(3), E(3), B(3), k

    v = (/1.0, 0.0, 0.0/)
    E = 0.0
    B = (/0.0, 0.0, 1.0/)
    k = 0.01

    call sub_A01_Boris_3Dxyz(v, E, B, k)
end program demo_a01

Compile from the repository root for the simplest relative include path:

gfortran -cpp -O2 -fdefault-real-8 demo_a01.f90

Note: many Fortran programs currently use default real. If double precision is required, add the corresponding compiler option, such as gfortran -fdefault-real-8. With Intel Fortran, use an option such as ifx -real-size 64. If a test directory’s make.sh already contains that option, run the script as written.

4. Which Modules Fit The PIC Workflow

AlgoPlasma is not a fixed PIC driver. It is a set of algorithm modules and subroutines that you can assemble into your own program. A common PIC program can be read as this workflow:

PIC workflow and related AlgoPlasma modules.

Use this table as the first module map:

PIC step	AlgoPlasma module	Common routine groups
Initialize particles and load initial data	I_Initializer, F_IO	I01_par_distribute, I02_par_init_and_load, F01_par_load, F03_field_load
Gather grid fields to particles	C_Gather	C01_gather_3Dxyz, C02_gather_3Dxyz_bspline
Push particles	A_Pusher	A01_Boris_3Dxyz, A02_Boris_3Drtz, A03_Higuera_Cary_relativistic_3Dxyz
Collisions	G_Collision	G01_MCC, G02_MCC_network
Deposit particles to grid	B_Scatter	B01_scatter_3Dxyz, B02_deposit_3d_cyl
Solve or update fields	D_Poisson, E_Maxwell	D01-D04 Poisson/HYPRE solvers, E01-E03 FDTD/CPML
Exchange MPI boundaries and particles	H_MPI_Exchange	H01_mpi_exchange_field, H02_mpi_exchange_par, H03_mpi_exchange_den
Output particles and fields	F_IO	F02_par_output, F04_field_output

Electrostatic PIC usually deposits charge with B_Scatter and then solves fields with D_Poisson. Electromagnetic PIC often deposits current too and updates fields with E_Maxwell. In MPI programs, H_MPI_Exchange may appear after field updates, after deposition, and after particles cross subdomain boundaries.

Learn Collisions with the G02 Example

This small example shows hot particles cooling through collisions with a colder gas. Zero-dimensional means no spatial variation; each velocity still has three components. Speed, kinetic energy and averages are enough to begin. From the repository root:

bash tests/009_collision/G02_MCC_network/examples/collision_box/run.sh

The script builds automatically. It needs CMake 3.20 or newer and C/C++ compilers with C++20 support; plots need Python 3 and Matplotlib. Fortran and MPI are not required by default. After collision_box: PASS, open the plots and checks.csv in the example’s results/ directory. The collision-box tutorial explains each plot and the pass criteria. The data are synthetic and intended for software validation.

The G02 Fortran interface links its C++ library. See the G02 module page for integration.

Calling Other Modules

• Start with the module directory’s README.en.md.

• Then read the related test page for run commands and output meaning.

• More complex modules may require MPI, HYPRE, HDF5, or Python plotting packages; use the module notes as the source of truth.

Common Sticking Points

• If run.sh cannot find build, run ./make.sh first.

• If make.sh fails to compile, check that gfortran exists and run the script from the test directory.

• If plot.sh fails, ignore it for calling AlgoPlasma and confirm that build/case*.dat exists.

• If the include path is not found, compile from the repository root or adjust the path relative to the current build directory.