compile.hpp：模型编译接口与运行时数据

Tip

  • majorant（频率上界）：一个不小于真实碰撞频率的数，用它安排候选事件，再按“真实频率÷上界”接受候选。上界过松会增加空碰撞；低于真实频率则报错。

这个文件做什么

这里的“编译”是整理碰撞数据，不是把 C++ 编译成机器码。CompileOptions 配置频率上界的安全系数等；CompiledReaction 保存已解析的反应信息，CompiledModel 供 MccEngine 使用。对应实现是 fun_G02_mcc_compile.cpp。

主要类型与入口

CompileOptions, CompiledReaction, CompiledModel; compile_model(ModelDefinition, CompileOptions)

上面列出的是入口名称，具体参数以源码声明为准。

What this file does

Compilation here means preparing collision data, not compiling C++. Options control bounds and validation; CompiledModel is consumed by MccEngine. Implemented in fun_G02_mcc_compile.cpp.

Main types and entry points

CompileOptions, CompiledReaction, CompiledModel; compile_model(ModelDefinition, CompileOptions)

The names above are an interface index; consult the source declarations for exact parameters.

源码 / Source

compile.hpp

  1// SPDX-License-Identifier: Apache-2.0
  2//
  3// 阅读指引：“编译模型”是把输入数据检查并整理成适合反复计算的形式，
  4// 不是调用 C++ 编译器。初始化时完成这些工作，碰撞循环就不用重复做。
  5
  6//
  7// Compiled, physics-validated collision network.
  8//
  9// compile_model() is the last point at which a bad model can be rejected
 10// cheaply. It checks the reaction order, the rate-law unit against that order,
 11// the supported angular/energy models, element and charge balance and the
 12// endothermic threshold, and it builds a *conservative* majorant from the
 13// analytic segments of every table. Adding a species or a supported two/three
 14// body channel only requires editing the CSV package.
 15#pragma once
 16
 17#include "model.hpp"
 18
 19#include <cstddef>
 20#include <cstdint>
 21#include <string>
 22#include <unordered_map>
 23#include <vector>
 24
 25namespace algoplasma {
 26namespace mcc {
 27
 28// majorant 是真实碰撞频率的上界，用它先抽候选事件，再筛出真实碰撞。
 29// 上界偏松会多抽到空碰撞；上界偏小可能漏事件，因此不能当作随意调小的加速参数。
 30struct CompileOptions {
 31    // Multiplies every conservative majorant.
 32    Real majorant_safety_factor{1.05};
 33    // Diagnostic-only global scale. Values below 1.0 deliberately under-bound
 34    // the rate so that tests can exercise the majorant-violation guard.
 35    // Production code must leave this at 1.0.
 36    Real diagnostic_majorant_scale{1.0};
 37    // Relative tolerance for momentum and energy residuals.
 38    Real relative_tolerance{1.0e-9};
 39    // Default per-step candidate-event cap (null + real events).
 40    std::uint32_t max_events_per_step{64};
 41};
 42
 43// 每个启用的反应对应一份预处理结果；保留 source_file/line 便于错误追溯。
 44struct CompiledReaction {
 45    ReactionId id{invalid_reaction};
 46    std::string name;
 47    CollisionAlgorithm algorithm{CollisionAlgorithm::C02Elastic};
 48    SpeciesId projectile{invalid_species};
 49    StateId projectile_state{invalid_state};
 50    std::vector<ReactantTerm> reactants; // as declared
 51    std::vector<ProductTerm> products;   // as declared
 52    // Expanded stoichiometry, projectile/background bodies in declaration order.
 53    std::vector<std::pair<SpeciesId, StateId>> reactant_bodies;
 54    std::vector<std::pair<SpeciesId, StateId>> product_bodies;
 55
 56    unsigned order{2};
 57    unsigned background_count{1};
 58
 59    // 能量字段统一用 eV：threshold 为阈值，q_value>0 表示释放能量，
 60    // ker_min 为碰后相对动能下限，radiated_energy 为辐射带走的能量。
 61    Real threshold_ev{};
 62    Real q_value_ev{};
 63    Real ker_min_ev{};
 64    Real radiated_energy_ev{};
 65    Real internal_before_ev{};
 66    Real internal_after_ev{};
 67    int charge_before{};
 68    int charge_after{};
 69
 70    AngularModel angular_model{AngularModel::Isotropic};
 71    Real angular_cos_min{};
 72    Real angular_cos_max{};
 73    EnergyModel energy_model{EnergyModel::NBodyPhaseSpace};
 74
 75    RateKind rate_kind{RateKind::CrossSection};
 76    Table table;
 77    std::string x_source; // "relative_energy_ev" or "temperature_k"
 78    SpeciesId x_species{invalid_species};
 79
 80    // Conservative majorant per unit density product (m^3/s or m^6/s):
 81    //   cross_section   max over segments of sigma(E) * v(E)
 82    //   rate_coefficient max over segments of k(x)
 83    Real majorant_shape{};
 84    std::vector<Real> segment_shape_bounds;
 85    Real applied_majorant_scale{1.0}; // safety * diagnostic
 86
 87    bool resonant{false};
 88    std::string source_file;
 89    std::size_t source_line{0};
 90
 91    [[nodiscard]] bool is_cross_section() const noexcept {
 92        return rate_kind == RateKind::CrossSection;
 93    }
 94};
 95
 96// 除反应表外还保存查询索引：按入射物种+能级快速找出候选通道。
 97class CompiledModel {
 98public:
 99    std::string name;
100    std::string version;
101    std::string package_dir;
102    SpeciesRegistry species;
103    StateRegistry states;
104    std::unordered_map<SpeciesId, std::map<std::string, unsigned>> composition;
105    std::vector<CompiledReaction> reactions;
106    CompileOptions options;
107
108    [[nodiscard]] const CompiledReaction& reaction(ReactionId id) const;
109    // Channels whose kinetic projectile is exactly (species, state). A channel
110    // is only eligible when the incoming primary particle matches its declared
111    // projectile state, so state is part of the lookup key.
112    [[nodiscard]] std::vector<std::size_t> reactions_for_projectile(SpeciesId id,
113                                                                    StateId state) const;
114    [[nodiscard]] const std::vector<std::size_t>& reactions_for_projectile_view(
115        SpeciesId id, StateId state) const noexcept;
116
117private:
118    std::unordered_map<ReactionId, std::size_t> by_id_;
119    std::unordered_map<std::uint32_t, std::vector<std::size_t>> by_projectile_state_;
120    friend CompiledModel compile_model(ModelDefinition, CompileOptions);
121};
122
123[[nodiscard]] CompiledModel compile_model(ModelDefinition model, CompileOptions options = {});
124
125} // namespace mcc
126} // namespace algoplasma

文件归属 / File location

G_Collision/G02_MCC_network/compile.hpp

Model