flash-sim 0.0.1__py3-none-any.whl

flash/input_gen/gen_sim_data/GEN_SIM_DATA_GUIDE.md

@@ -0,0 +1,306 @@
+# gen_sim_data 说明文档
+
+## 概述
+
+`gen_sim_data` 子包用于生成 FLASH 仿真的 `Simulation_data.F90` 文件。该文件是 FLASH 仿真 setup 的核心模块之一，用于**定义和存储仿真的运行时参数变量**。
+
+**生成器类型**: 自包含生成器（硬编码模板）  
+**输出文件**: `Simulation_data.F90`  
+**输出位置**: `SimulationMain/<SetupName>/Simulation_data.F90`
+
+---
+
+## Simulation_data.F90 文件结构
+
+### 标准格式
+
+```fortran
+!!****if* source/Simulation/SimulationMain/<SetupName>/Simulation_data
+!!
+!! NAME
+!!  Simulation_data
+!!
+!! SYNOPSIS
+!!  Use Simulation_data
+!!
+!! DESCRIPTION
+!!  Stores the local data for Simulation setup: <SetupName>
+!!
+!! PARAMETERS
+!!  <参数说明>
+!!
+!!***
+
+module Simulation_data
+
+  implicit none
+#include "constants.h"   ! 或 #include "Eos.h" 等
+
+  !! *** Runtime Parameters *** !!
+  real,    save :: sim_param1, sim_param2
+  integer, save :: sim_intParam
+  logical, save :: sim_boolParam
+
+  !! *** Variables pertaining to this Simulation *** !!
+  integer, parameter :: sim_nProfile = 1000
+  real, dimension(sim_nProfile), save :: sim_rProf, sim_rhoProf
+
+end module Simulation_data
+```
+
+---
+
+## 参数分类（基于 139 个 refs 示例）
+
+### 1. 通用参数（几乎所有仿真）
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| `sim_smallX` | real | 最小物质分数 |
+| `sim_smallRho` | real | 最小密度 |
+| `sim_smallP` | real | 最小压力 |
+| `sim_pi` | real | π 常数 |
+| `sim_meshMe` | integer | MPI 进程 ID |
+| `sim_killdivb` | logical | 是否清除磁场散度 |
+
+### 2. 域定义参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| `sim_xMin`, `sim_xMax` | real | X 轴范围 |
+| `sim_yMin`, `sim_yMax` | real | Y 轴范围 |
+| `sim_zMin`, `sim_zMax` | real | Z 轴范围 |
+| `sim_Lx`, `sim_Ly`, `sim_Lz` | real | 域长度 |
+| `sim_initGeom` | character | 初始几何类型 |
+
+### 3. 流体仿真参数
+
+#### 3.1 欧拉流体（Hydro）
+
+| 参数名 | 说明 |
+|--------|------|
+| `sim_rhoAmbient` | 环境密度 |
+| `sim_pAmbient` | 环境压力 |
+| `sim_gamma` | 绝热指数 |
+| `sim_expEnergy` | 爆炸能量（Sedov） |
+| `sim_rInit` | 初始激波位置 |
+
+#### 3.2 磁流体（MHD）
+
+| 参数名 | 说明 |
+|--------|------|
+| `sim_BxAmbient` | X 方向环境磁场 |
+| `sim_betaAmbient` | 环境等离子体 β |
+| `sim_neAmbient` | 环境电子密度 |
+| `sim_dBPert` | 磁场扰动幅度 |
+| `sim_modeNumb` | 波模数 |
+
+### 4. 激光-等离子体参数（LaserSlab 系列）
+
+| 参数名 | 说明 |
+|--------|------|
+| `sim_rhoTarg` | 靶密度 |
+| `sim_teleTarg` | 靶电子温度 |
+| `sim_tionTarg` | 靶离子温度 |
+| `sim_tradTarg` | 靶辐射温度 |
+| `sim_eosTarg` | 靶 EOS 类型 |
+| `sim_rhoCham` | 腔密度 |
+| `sim_teleCham` | 腔电子温度 |
+| `sim_targetRadius` | 靶半径 |
+| `sim_targetHeight` | 靶高度 |
+| `sim_vacuumHeight` | 真空区域高度 |
+
+### 5. 辐射流体参数（RadSlab 等）
+
+| 参数名 | 说明 |
+|--------|------|
+| `sim_radSourceType` | 辐射源类型 |
+| `sim_radSourceTMax` | 辐射源最大时间 |
+| `sim_radSourcePeak` | 辐射源峰值 |
+| `sim_radSourceFWHM` | 辐射源半高宽 |
+| `sim_nGroups` | 辐射能群数量 |
+| `sim_mgdDomainBC` | 多群边界条件 |
+
+### 6. 重力/天体物理参数
+
+| 参数名 | 说明 |
+|--------|------|
+| `sim_boltz` | 玻尔兹曼常数 |
+| `sim_mH` | 氢原子质量 |
+| `sim_newt` | 万有引力常数 |
+| `sim_absErrMax` | 绝对误差上限 |
+| `sim_relErrMax` | 相对误差上限 |
+
+### 7. EOS 相关参数
+
+| 参数名 | 说明 |
+|--------|------|
+| `sim_eosArr` | EOS 参数数组 |
+| `sim_vecLen` | 向量长度 |
+| `sim_mode` | EOS 模式 |
+| `sim_abar_1`, `sim_abar_2` | 平均原子量 |
+| `sim_gamma_1`, `sim_gamma_2` | 绝热指数 |
+
+### 8. 剖面数据数组（用于复杂初始条件）
+
+```fortran
+integer, parameter :: sim_nProfile = 1000
+real, dimension(sim_nProfile), save :: sim_rProf   ! 径向坐标
+real, dimension(sim_nProfile), save :: sim_rhoProf ! 密度剖面
+real, dimension(sim_nProfile), save :: sim_pProf   ! 压力剖面
+real, dimension(sim_nProfile), save :: sim_vProf   ! 速度剖面
+```
+
+---
+
+## 生成器 API
+
+### 当前实现（硬编码模板）
+
+```python
+from gen_sim_data import SimDataGenerator
+
+generator = SimDataGenerator()
+content = generator.generate()  # 返回 LaserSlab1d 模板
+generator.save("path/to/Simulation_data.F90")
+```
+
+### 模板来源
+
+当前模板从 `LaserSlab1d/Simulation_data.F90` 提取，包含：
+- 靶参数（`sim_rhoTarg`, `sim_teleTarg` 等）
+- 腔参数（`sim_rhoCham`, `sim_teleCham` 等）
+- 几何参数（`sim_targetRadius`, `sim_initGeom` 等）
+
+---
+
+## 扩展生成器（未来工作）
+
+当前生成器使用单一硬编码模板。如果需要支持多种仿真类型，可以扩展为：
+
+```python
+class SimDataGenerator:
+    TEMPLATES = {
+        "LaserSlab": "...",  # 激光等离子体模板
+        "Sedov": "...",      # Sedov 爆炸模板
+        "MHD": "...",        # 磁流体模板
+        "RadHydro": "...",   # 辐射流体模板
+    }
+    
+    def generate(self, setup_type: str = "LaserSlab", **params):
+        """根据 setup_type 选择模板并填充参数。"""
+        template = self.TEMPLATES[setup_type]
+        return template.format(**params)
+```
+
+---
+
+## 使用示例
+
+### 示例 1：生成 LaserSlab 的 Simulation_data.F90
+
+```python
+from physimx_sim.flash.input_gen.gen_sim_data import SimDataGenerator
+
+generator = SimDataGenerator()
+output_path = generator.save(
+    "FLASH4.8/source/Simulation/SimulationMain/LaserSlab1d/Simulation_data.F90"
+)
+print(f"Generated: {output_path}")
+```
+
+### 示例 2：典型 Simulation_data.F90 内容（LaserSlab）
+
+```fortran
+module Simulation_data
+
+  implicit none
+#include "constants.h"
+
+  !! *** Runtime Parameters *** !!  
+  real, save :: sim_targetRadius
+  real, save :: sim_targetHeight
+  real, save :: sim_vacuumHeight
+
+  real,    save :: sim_rhoTarg  
+  real,    save :: sim_teleTarg 
+  real,    save :: sim_tionTarg 
+  real,    save :: sim_tradTarg 
+  real,    save :: sim_zminTarg
+  integer, save :: sim_eosTarg
+
+  real,    save :: sim_rhoCham  
+  real,    save :: sim_teleCham 
+  real,    save :: sim_tionCham 
+  real,    save :: sim_tradCham 
+  integer, save :: sim_eosCham  
+
+  logical, save :: sim_killdivb = .FALSE.
+  real, save :: sim_smallX
+  character(len=MAX_STRING_LENGTH), save :: sim_initGeom
+
+end module Simulation_data
+```
+
+---
+
+## 与其他生成器的关系
+
+`Simulation_data.F90` 通常与以下文件配合使用：
+
+| 文件 | 生成器 | 关系 |
+|------|--------|------|
+| `Config` | `gen_config` | 定义运行时参数默认值 |
+| `Simulation_init.F90` | `gen_sim_init` | 读取 Config 参数并初始化 Simulation_data |
+| `Simulation_initBlock.F90` | `gen_sim_initblock` | 使用 Simulation_data 中的参数设置初始条件 |
+| `example.par` | `gen_par` | 设置仿真参数（部分参数与 Simulation_data 对应） |
+
+**重要**: `Config` 中定义的参数会在仿真启动时读入，然后在 `Simulation_init.F90` 中存储到 `Simulation_data` 模块的变量中。
+
+---
+
+## 常见仿真类型的 Simulation_data 示例
+
+### 1. LaserSlab（激光等离子体）
+
+**文件**: `refs/Simulation_data (10).F90`, `(50).F90`, `(100).F90` 等  
+**关键参数**: `sim_rhoTarg`, `sim_teleTarg`, `sim_rhoCham`
+
+### 2. Sedov（爆炸波）
+
+**文件**: `refs/Simulation_data (113).F90` 等  
+**关键参数**: `sim_expEnergy`, `sim_rhoAmbient`, `sim_pAmbient`
+
+### 3. MHD（磁流体）
+
+**文件**: `refs/Simulation_data (10).F90` (HallWhistlerWaves)  
+**关键参数**: `sim_BxAmbient`, `sim_betaAmbient`, `sim_modeNumb`
+
+### 4. 辐射流体（RadSlab）
+
+**文件**: `refs/Simulation_data (100).F90`  
+**关键参数**: `sim_radSourceType`, `sim_nGroups`
+
+---
+
+## 注意事项
+
+1. **参数命名约定**: 所有参数以 `sim_` 开头，后接驼峰命名（如 `sim_rhoTarg`）
+2. **保存属性**: 所有变量必须使用 `save` 属性，确保在仿真过程中持久化
+3. **include 文件**: 根据使用的 FLASH 模块选择 `#include "constants.h"` 或 `#include "Eos.h"`
+4. **数组剖面**: 复杂初始条件可能需要 allocatable 数组存储剖面数据
+5. **与 Config 同步**: `Simulation_data.F90` 中声明的变量必须在 `Config` 中有对应的运行时参数定义
+
+---
+
+## 文件清单
+
+- **生成器**: `gen_sim_data/generator.py`
+- ** refs 示例**: `gen_sim_data/refs/Simulation_data (*).F90` (139 个)
+- **输出文件**: `SimulationMain/<SetupName>/Simulation_data.F90`
+
+---
+
+## 更新日期
+
+2026-07-03

flash/input_gen/gen_sim_data/__init__.py

@@ -0,0 +1,10 @@
+"""
+gen_sim_data — Simulation_data.F90 文件生成
+
+从 scenarios/flash_demo/LaserSlab1d/Simulation_data.F90 模板生成。
+Simulation_data.F90 定义 FLASH 仿真运行时参数变量。
+"""
+
+from .generator import SimDataGenerator
+
+__all__ = ["SimDataGenerator"]

flash/input_gen/gen_sim_data/generator.py

@@ -0,0 +1,87 @@
+"""
+Simulation_data.F90 文件生成器 (自包含)
+═══════════════════════════════════════
+
+内容从 LaserSlab1d/Simulation_data.F90 模板提取后硬编码。
+"""
+
+from pathlib import Path
+from typing import List, Optional, Union
+
+
+DEFAULT_SIM_DATA_F90 = """\
+!!****if* source/Simulation/SimulationMain/LaserSlab/Simulation_data
+!!
+!! NAME
+!!  Simulation_data
+!!
+!! SYNOPSIS
+!!  Use Simulation_data
+!!
+!! DESCRIPTION
+!!
+!!  Store the simulation data
+!!
+!! 
+!!***
+module Simulation_data
+
+  implicit none
+
+#include "constants.h"
+
+  !! *** Runtime Parameters *** !!  
+  real, save :: sim_targetRadius
+  real, save :: sim_targetHeight
+  real, save :: sim_vacuumHeight
+
+  real,    save :: sim_rhoTarg  
+  real,    save :: sim_teleTarg 
+  real,    save :: sim_tionTarg 
+  real,    save :: sim_tradTarg 
+  real,    save :: sim_zminTarg
+  integer, save :: sim_eosTarg
+
+  real,    save :: sim_rhoCham  
+  real,    save :: sim_teleCham 
+  real,    save :: sim_tionCham 
+  real,    save :: sim_tradCham 
+  integer, save :: sim_eosCham  
+
+  logical, save :: sim_killdivb = .FALSE.
+  real, save :: sim_smallX
+  character(len=MAX_STRING_LENGTH), save :: sim_initGeom
+
+
+end module Simulation_data
+"""
+
+
+class SimDataGenerator:
+    """Simulation_data.F90 文件生成器 (自包含)。
+
+    内容从 LaserSlab1d/Simulation_data.F90 提取并硬编码。
+    """
+
+    def generate(self, species: Optional[List[str]] = None) -> str:
+        """生成 Simulation_data.F90 内容。
+
+        Args:
+            species: species 列表（预留，暂不处理）
+
+        Returns:
+            Simulation_data.F90 内容字符串
+        """
+        return DEFAULT_SIM_DATA_F90
+
+    def save(
+        self,
+        output_path: Union[str, Path],
+        species: Optional[List[str]] = None,
+    ) -> Path:
+        """生成并保存 Simulation_data.F90。"""
+        content = self.generate(species=species)
+        out = Path(output_path)
+        out.parent.mkdir(parents=True, exist_ok=True)
+        out.write_text(content, encoding="utf-8")
+        return out

flash/input_gen/gen_sim_init/GEN_SIM_INIT_GUIDE.md

@@ -0,0 +1,216 @@
+# gen_sim_init — Simulation_init.F90 生成器说明文档
+
+## 目录
+1. [概述](#概述)
+2. [Simulation_init.F90 文件格式](#simulation_initf90-文件格式)
+3. [gen_sim_init 生成器 API](#gen_sim_init-生成器-api)
+4. [使用示例](#使用示例)
+5. [参考示例 (refs/)](#参考示例-refs)
+6. [常见问题](#常见问题)
+
+---
+
+## 概述
+
+`gen_sim_init` 子包用于生成 FLASH 仿真的 `Simulation_init.F90` 文件。这个Fortran子程序初始化仿真参数，从 `.par` 文件中读取运行时参数并存储在模块变量中。
+
+**生成器类型**: 自包含（硬编码默认模板）
+**默认模板来源**: `SimulationMain/LaserSlab/Simulation_init.F90`
+**输出文件**: `Simulation_init.F90`
+
+---
+
+## Simulation_init.F90 文件格式
+
+### 基本结构
+
+```fortran
+!!****if* source/Simulation/SimulationMain/LaserSlab/Simulation_init
+!!
+!! NAME
+!!
+!!  Simulation_init
+!!
+!! SYNOPSIS
+!!
+!!  Simulation_init()
+!!
+!! DESCRIPTION
+!!
+!!  Initializes all the parameters needed for a particular simulation
+!!
+!! PARAMETERS
+!!
+!!***
+
+subroutine Simulation_init()
+  use Simulation_data
+  use RuntimeParameters_interface, ONLY : RuntimeParameters_get
+  
+  implicit none
+
+#include "constants.h"
+#include "Flash.h"
+
+  ! 读取运行时参数
+  call RuntimeParameters_get('sim_targetRadius', sim_targetRadius)
+  call RuntimeParameters_get('sim_rhoTarg', sim_rhoTarg)
+  ! ...
+
+end subroutine Simulation_init
+```
+
+### 关键部分
+
+1. **头注释**: 遵循FLASH文档规范
+2. **use声明**: 引入需要的模块
+3. **参数读取**: 使用 `RuntimeParameters_get` 读取 `.par` 文件中的参数
+4. **初始化逻辑**: 可选的特殊初始化代码
+
+---
+
+## gen_sim_init 生成器 API
+
+### 类: SimInitGenerator
+
+**位置**: `gen_sim_init/generator.py`
+
+### 方法: generate(params)
+
+生成 `Simulation_init.F90` 内容。
+
+**签名**:
+```python
+def generate(self, params: Optional[Dict[str, Any]] = None) -> str:
+```
+
+**参数**:
+- `params`: 可选参数字典（预留，当前未使用）
+
+**返回**: Fortran源代码字符串
+
+### 方法: save(output_path, params)
+
+生成并保存文件。
+
+**签名**:
+```python
+def save(
+    self,
+    output_path: Union[str, Path],
+    params: Optional[Dict[str, Any]] = None,
+) -> Path:
+```
+
+---
+
+## 使用示例
+
+### 示例 1: 生成默认 Simulation_init.F90
+
+```python
+from gen_sim_init import SimInitGenerator
+
+generator = SimInitGenerator()
+
+# 生成默认内容（基于LaserSlab模板）
+content = generator.generate()
+
+# 保存
+output_path = generator.save("path/to/Simulation/Simulation_init.F90")
+print(f"Saved to: {output_path}")
+```
+
+### 示例 2: 自定义 Simulation_init.F90（高级）
+
+当前生成器使用硬编码模板。如需自定义，可以修改生成的字符串：
+
+```python
+generator = SimInitGenerator()
+
+# 生成默认内容
+content = generator.generate()
+
+# 修改内容（例如，添加自定义参数读取）
+custom_lines = """
+  ! 读取自定义参数
+  call RuntimeParameters_get('my_custom_param', my_custom_param)
+"""
+
+# 在 "implicit none" 之后插入
+lines = content.split("\n")
+insert_idx = 0
+for i, line in enumerate(lines):
+    if "implicit none" in line:
+        insert_idx = i + 1
+        break
+lines.insert(insert_idx, custom_lines)
+content = "\n".join(lines)
+
+# 保存
+with open("path/to/Simulation/Simulation_init.F90", "w") as f:
+    f.write(content)
+```
+
+---
+
+## 参考示例 (refs/)
+
+`gen_sim_init/refs/` 目录包含 143+ 个 `Simulation_init.F90` 示例，来自不同的FLASH仿真。
+
+### 主要示例
+
+| 示例 | 描述 |
+|------|------|
+| `Simulation_init.F90` | 基础LaserSlab版本 |
+| `Simulation_init (10).F90` ... | 各种变体 |
+
+### 如何参考这些示例
+
+1. **查看示例**: 直接读取 `refs/` 中的文件
+2. **了解初始化模式**: 不同仿真如何读取和初始化参数
+3. **提取关键代码**: 复制需要的代码片段
+
+**示例**: 参考 Sod 的 `Simulation_init.F90`
+
+```bash
+cat gen_sim_init/refs/Simulation_init.F90 | head -50
+
+# 提取关键部分:
+# - 如何读取左右状态参数
+# - 如何设置初始条件
+```
+
+---
+
+## 常见问题
+
+### 1. 如何为新的仿真类型生成 Simulation_init.F90？
+
+**答**: 当前生成器使用硬编码的LaserSlab模板。如需其他类型：
+1. 生成默认版本
+2. 手动修改以匹配目标仿真的初始化需求
+3. 或将需要的示例复制到 `refs/` 目录，并扩展生成器
+
+### 2. Simulation_init.F90 和 Simulation_initBlock.F90 有什么区别？
+
+**答**:
+- `Simulation_init.F90`: 初始化仿真级参数（一次）
+- `Simulation_initBlock.F90`: 初始化每个块的流体数据（每个块调用一次）
+
+### 3. 如何验证生成的 Fortran 代码是否正确？
+
+**答**: 使用FLASH编译：
+
+```bash
+cd /path/to/FLASH4.8
+make
+```
+
+如果Fortran代码有语法错误，编译时会报错。
+
+---
+
+**文档版本**: 1.0
+**最后更新**: 2026-07-03
+**维护**: PhySimX Team

flash/input_gen/gen_sim_init/__init__.py

@@ -0,0 +1,9 @@
+"""
+gen_sim_init — Simulation_init.F90 文件生成
+
+从 scenarios/flash_demo/LaserSlab/Simulation_init.F90 模板生成。
+"""
+
+from .generator import SimInitGenerator
+
+__all__ = ["SimInitGenerator"]