# YHLAPINE

**Repository Path**: e-level-parallel-algorithm/yhlapine

## Basic Information

- **Project Name**: YHLAPINE
- **Description**: LAPINE（Laser And Plasmas Interaction Numeric Experiment）是用于模拟激光和等离子体间的相互作用的并行程序，可用于二维或三维的PIC粒子模拟，采用了一系列最新的PIC粒子模拟算法，提升了计算速度。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2021-02-24
- **Last Updated**: 2023-01-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# YHLAPINE
## 一 软件概述
### 1.1 软件功能
YHLAPINE（YinHe Laser And Plasmas Interaction Numeric Experiment）由国防科技大学徐涵研究员开发。该程序是用于模拟激光和等离子体间相互作用的分布式并行程序，可用于二维或三维的PIC粒子模拟，采用了一系列最新的PIC粒子模拟算法，提升了计算速度。当前程序已经实现的功能有：
- 采用面向对象的C++技术，使程序易于扩展和维护，大量使用指针操作，节约存储空间。
- 通过条件编译，可以分别形成二维或三维的PIC模拟。
- 实现3维并行分区，提高并行粒度。同时三维分区容易实现针对不同物理模型合理分区，减小负载失衡，降低分区间交换的消息长度。
- 实现了断点续算功能，可以通过输入参数控制在任意断点处实现停机续算，为在大系统上的长时间运算提供了可能。
- 实现了移动窗口功能，使得模拟的区域能够随着时间的推移不断调整，适合于模拟激光在气体等离子体中的长距离传播这类问题。
### 1.2 软件结构
YHLAPINE源程序包含三个子目录，分别为**src/**, **post/**, **run/**, **doc/**:
- **src 目录**：源代码目录，包含所有的.h头文件和.cpp源程序。其中的Makefile文件控制编译过程，生成的可执行文件yhlapine通常会拷贝一份到../run目录下。
- **run 目录**：程序的运行目录，包含可执行文件和输入文件，输入文件后缀名为.inp。并且存放所有生成hdf5格式数据，这些数据不能直接阅读，只能由hdf5的API函数调用（由已经写好的post下的后处理软件包来处理），生成ASC格式的数据供画图软件使用。
- **post 目录**：包含用于数据后处理的一些程序源代码和头文件，这些文件可以单独编译生成可执行代码，对数据处理后生成可以画图的各种格式。
- **doc 目录**：存放了yhlapine用户手册。
### 1.3 软件算法
YHLAPINE的并行方案是将计算的粒子数均匀的分配到各个计算节点，而将定义在网格点的电场强度，磁场强度，电荷密度，电流密度等量存储到所有的计算节点，将推动粒子运动，由空间粒子分布求电荷，电流密度完全并行处理，然后将各个节点上的电荷，电流密度累加，再将总的密度广播到各个节点，然后各节点同时求解Maxwell方程。

## 二 软件安装
YHLAPINE程序采用C++语言进行开发，采用**Makefile**进行编译。
### 2.1 依赖项
YHLAPINE软件需要依赖3个基础库：zlib，szip，hdf5。需要通过修改Makefile文件中相应变量来指定依赖库的位置。

*注意：由于hdf5依赖于zlib和szip，所以须先安装zlib和szip，再安装hdf5。*
### 2.2 make
YHLAPINE程序采用**make**进行编译，Makefile文件位于src/Makefile。在正式编译yhlapine之前，需要先修改Makefile文件中如下内容：
- 编译器位置
```
CXX = /path/to/mpicxx
```
- 依赖库位置
```
HDF5_ROOT = /path/to/hdf5_dir
ZLIB_ROOT = /path/to/zlib_dir
SZIP_ROOT = /path/to/szip_dir
```
- 编译选项
```
DEFINES = -DDIM_TWO -DPARALLEL
    注：
    -DDIM_TWO(可选) : 编译生成二维粒子模拟代码，否则则生成三维模拟代码
    -DLOWPRECISION(可选) : 浮点变量以单精度表示（节约存储空间），否则以双精度表示
    -DPARALLEL(可选) : 编译生成并行执行代码，否则为串行代码
    -DDEBUG(可选) : 调试开发用，开启后程序运行会输出很多打印信息
```

Makefile修改完成后，键入make,进行编译和链接：
```
make
```
编译完成后，将在src/路径生成可执行文件**yhlapine**，同时在run/路径生成备份。

## 三 软件运行
YHLAPINE在run/路径下进行激光与等离子体作用模拟，默认使用lapine.inp文件作为控制参数的输入文件。在post/路径下进行数据成像后处理，可以生成相应的可视化图像。
### 3.1 输入文件
模拟程序默认使用run/路径下的`lapine.inp`作为输入文件，也可通过运行时选项来指定`.inp文件`，命令行形如：
```
mpirun -n 8 ./yhlapine example.inp
```
.inp输入文件中需要指定等离子体参数、激光参数、以及输出文件等相关参数。其文件结构包含若干节，每一节以`'@'`开始，以`'#'`开头的都为注释项;节之下还有以某些固定关键词开头的若干输入项，所有关键词都是大小写敏感的，而且不能改变。输入文件共包含如下7节：

| 小节选项 |主要设置参数 |
|---|---|
| @plasma |等离子体相关参数设置|
| @laser |激光相关参数设置|
| @box |模拟区域网格参数设置|
| @parallel |并行参数设置|
| @propagate |模拟时间以及保存数据的步数设置|
| @moveWindow |移动窗口功能相关参数设置|
| @diagnostic |诊断选项设置，程序输出结果保存控制参数|


各类参数的含义及设置，具体可参考doc/路径下的用户手册。

### 3.2 输出文件
模拟程序的输出文件位于run/路径下，既是结果文件，也是重启文件。主要包含2类文件，第一类包含电磁场信息,文件名以`Fields-`开头；第二类包含粒子信息，文件名以`Particles-`开头，并均以HDF5数据库格式`.H5文件`存储。输出文件由一系列名称形式为`$class-$time_step-$iprocs.H5`的文件组成,`class`表示信息类型，`time_step`表示时间步,`iprocs`表示进程号。
若输入文件中prop_save=3.0，nproc=2，那么输出文件将按照每3个时间步长保存一次信息，每个时间步中，2个进程分别对应4个文件，形式如下：
|场信息	|粒子信息|
|---|---|
|Fields-3.00-0.H5	|Particles-3.00-0.H5|
|Fields-3.00-1.H5	|Particles-3.00-1.H5|
|…	|…|
|Fields-6.00-0.H5	|Particles-6.00-0.H5|
|Fields-6.00-1.H5	|Particles-6.00-1.H5|
|…	|…|
|Fields-9.00-2.H5	|Particles-9.00-2.H5|
|Fields-9.00-3.H5	|Particles-9.00-3.H5|
|…	|…|


各输出文件内的详细信息，可参考doc/路径下的用户手册。

### 3.3 后处理
对数据进行成像后处理的模块位于post/路径下，在post/ASC目录下执行**make**后，生成4个可执行文件，用途如下表：
|可执行文件名称	|用途|
|---|---|
|Field_plot	|将前缀为Fields的H5文件转化为ASC文件|
|Particle_plot	|将前缀为Particles的H5文件转化为ASC文件|
|Phase_plot	|将前缀为Phases的H5文件转化为ASC文件|
|Spectrum_plot	|将前缀为Spectrums的H5文件转化为ASC文件|


各个后处理程序的运行时参数详细说明，可参考doc/路径下的用户手册。