阅读选项

本指南暂时托管至个人博客。

MoltenMeta 是一个面向液态合金热力学的计算与可视化平台，支持热力学计算、不确定性量化和模块化扩展。

核心概念

架构分层

UI (PySide6) → Application Services → Modules (plugins) → Data (SQLite)

依赖注入：通过 AppContext 获取服务（context.modules、context.user_db 等），避免全局单例。

两阶段初始化：

• bootstrap()：创建核心服务（Log、I18n、Theme）
• initApp()：加载数据库和模块

双数据库：

• core.mmdb：应用设置
• user DB：元素、系统、属性值等业务数据

模块系统

模块通过 config.toml 配置，无需继承基类（duck typing）。

runtime/modules/
├── kohler_module/
│   └── config.toml
├── toop_module/
│   └── config.toml
└── ...

数据源注册：模块通过 DataSourceRegistry.register(tag, factory) 注册数据源，供其他模块查询。

安装配置

环境要求

快速开始

# 安装依赖
uv sync

# 运行应用
uv run python src/main.py --runtime-path ./runtime

C++ 扩展编译

计算密集型模块使用 C++ 编写，通过 Pybind11 绑定：

module_name_module/
├── module_name_module.py    # Python wrapper
├── module_name_algorithm.cpp # C++ 实现
├── CMakeLists.txt
└── lib/
    └── module_name_algorithm.so  # 编译产物

.so（Linux）/ .pyd（Windows）/ .dylib（macOS）文件放入 lib/ 目录，Python 通过 importlib 动态加载。

核心 API

BinaryDataProvider

二元数据提供者接口。几何模型通过此接口获取二元数据。

class BinaryDataProvider(ABC):
    def get_values(self, elem_1: int, elem_2: int, x_array: list[float]) -> list[float]:
        """获取二元属性值数组"""

DataSourceRegistry

数据源工厂注册表。通过标签查找数据源。

class DataSourceRegistry:
    @classmethod
    def register(cls, tag: str, factory: Callable) -> None: ...
    
    @classmethod
    def findByTag(cls, required_tags, accepted_tags, module_service=None) -> list: ...

ModuleService

模块加载和调用的核心服务。

class ModuleService:
    def callMethod(self, module_name: str, method_name: str, **kwargs) -> dict: ...
    
    def setProvider(self, module_name: str, provider: BinaryDataProvider) -> None: ...

几何模型

参数约定

AB → AC → BC（按字母序）

四种模型

Kohler（对称）：

Z_ABC = (x_A+x_B)²·Z_AB(x_A/(x_A+x_B)) 
      + (x_B+x_C)²·Z_BC(x_B/(x_B+x_C)) 
      + (x_A+x_C)²·Z_AC(x_A/(x_A+x_C))

Toop（非对称，A 为溶剂）：

Z_ABC = x_B/(x_B+x_C)·Z_AB(x_A) + x_C/(x_B+x_C)·Z_AC(x_A) 
      + (x_B+x_C)²·Z_BC(x_B/(x_B+x_C))

Maggianu（体积分数修正）：

V_ij = (1 + x_i - x_j) / 2
Z_ABC = x_A·x_B/(V_AB·V_BA)·Z_AB(V_AB) + ...

Hillert-Toop（混合）：

Z_ABC = x_B/(x_B+x_C)·Z_AB(x_A) + x_C/(x_B+x_C)·Z_AC(x_A) 
      + x_B·x_C/(V_BC·V_CB)·Z_BC(V_BC)

计算链路

GP → RK → Butler

实验数据 → GP.fit() → GP.predict() → 残差预测
    ↓
二元数据 → RK.fit() → L_coeffs + Σ_L
                ↓
          get_GE_functions()
                ↓
ButlerConfig ← sigma_i_func, density_func, element_props_get_M
                ↓
         ButlerCalc.solve() → σ(x, T)
                ↓
          sample() → Monte Carlo 不确定性传播

数据持久化

Snapshot 模式

数据实体使用 frozen=True 的 dataclass，确保不可变。

class SnapshotBase(ABC):
    id: int | None

    @classmethod
    def fromRow(cls, row) -> "SnapshotBase": ...

    def toRecord(self) -> dict: ...

Repository 模式

class BaseRepository(ABC, Generic[T]):
    def insert(self, entity: T) -> int: ...
    def findById(self, id: int) -> T | None: ...
    def findAll(self) -> List[T]: ...
    def update(self, entity: T) -> bool: ...
    def delete(self, id: int) -> bool: ...

config.toml 参考

[module]
package_name = "kohler_module"
entry_class = "KohlerCalc"
all_methods = ["calculateSingleProperty", "calculateScatter", "calculateContour"]
type = "simulation"
category = "geometric_model"

[calculateSingleProperty.inputs]
symbol = ["elem_A", "elem_B", "elem_C", "x_A", "x_B", "x_C", "Z_AB", "Z_BC", "Z_AC"]
input_method = "raw"

[calculateSingleProperty.outputs]
symbol = ["Z_ABC"]
is_virtual = true

[calculateSingleProperty.plot]
plotType = "scatter_3d"

常见问题

Linux Wayland 问题

问题：Qt-Advanced-Docking-System 在 Wayland 会话下停靠和拖拽异常。

解决：使用 X11 会话（登录界面选择 "GNOME on Xorg"）。

模块加载失败

检查项：

1. config.toml 存在且格式正确
2. entry_class 拼写正确
3. 模块目录在 runtime/modules/ 下
4. registerDataSources() 正确注册

数据源查询返回空

检查项：

1. 数据源已注册到 DataSourceRegistry
2. 标签匹配（required_tags 和 accepted_tags）
3. 数据库中已有数据

C++ 扩展加载失败

检查项：

1. 编译产物（.so/.pyd/.dylib）在 lib/ 目录
2. Python 版本与扩展编译版本匹配
3. importlib.util.spec_from_file_location 路径正确

GP 训练不收敛

建议：

• 使用 kernel_type="Matern" 而非 "RBF"（更稳健）
• 调整 alpha 参数（越小越容易过拟合）
• 小数据集（< 30 点）考虑固定 length_scale

相关链接

• GitHub Issues
• 技术支持：[email protected]