first commit

Author: llphhl

README.md

@@ -0,0 +1,170 @@
+# 三世界理论动态演化模型 (RX-GML / GM4.5.2)
+
+## 项目简介
+
+本项目旨在通过一个动态演化的多主体模型，探索和可视化一个关于个体“现实”构成的理论。该理论源于一段意识流文字，其核心观点认为个体的现实是由“本然”、“应然”和“或然”三个相互作用的世界所构成。
+
+*   **本然 (The Inherent/Given)：** 代表个体所拥有的客观资源、条件以及面临的限制和障碍。
+*   **应然 (The Ought-to-be/Normative)：** 代表个体的价值观、信念、驱动力、理想和目标。
+*   **或然 (The Probable/Potential)：** 代表个体感知的可能性、选择空间、创新能力和风险承受意愿。
+
+模型中的每个“个体”（或称“状态点”）拥有这三大世界下的多个具体维度。这些维度值在0-10之间动态变化，其演化逻辑基于一系列内部反馈循环、对外部环境的响应、社会交互以及随机事件的影响。
+
+本项目通过一个基于Python Dash构建的Web应用程序，将这些状态点及其演化过程在三维空间中进行可视化，并允许用户通过交互式控件调整参数、观察演化、甚至手动编辑状态点的维度。
+
+**核心特性：**
+
+*   **多维度个体建模：** 每个个体包含本然、应然、或然三大类下的多个细分维度。
+*   **动态演化算法：** 复杂的内部逻辑驱动各维度随时间变化，体现了维度间的相互促进与制约。
+*   **深化风险与回报机制：** 模拟个体在面对不确定性时的决策、投资、以及成功或失败后的连锁反应。
+*   **完善的“应然”世界动态：** 强调价值观、驱动力和理想在指导行为、应对现实中的核心作用。
+*   **社会交互系统：** 引入邻居网络、信任机制、信息传播、声望系统等，模拟个体间的相互影响。
+*   **事件系统：** 随机或条件触发的全局/个体事件为模型增加不确定性和转折点。
+*   **全局环境因素：** 模拟宏观环境对个体演化的系统性影响。
+*   **交互式可视化：** 通过Dash在浏览器中实时展示三维演化过程和相关数据。
+
+## 代码结构与说明
+
+项目主要由一个Python脚本 (`RX-GML.py` 或你最终命名的文件) 构成，其中包含了以下主要部分：
+
+### 1. 全局常量与辅助函数
+
+*   `DIM_KEYS`: 包含所有个体维度的键名列表（如 `b1_resource`, `s1_trustworthiness` 等）。
+*   `DIMENSION_LABELS_MAP_ZH`: 维度键名到中文标签的映射，用于UI显示。
+*   `AXIS_LABELS_ZH`: 坐标轴标签的中文映射。
+*   `MAX_LOG_LINES`: 事件日志显示的最大行数。
+*   `sigmoid(x, k, x0)`: S型函数，用于模拟饱和效应或阈值效应。
+*   `scale_value(value, old_min, old_max, new_min, new_max)`: 将值从一个范围映射到另一个范围的辅助函数。
+
+### 2. `WorldState` 类
+
+此类定义了模型中的核心实体——“个体”或“状态点”。
+
+*   **`__init__(...)`**: 初始化个体的所有维度值（本然、应然、或然、社交维度），以及历史记录、邻居列表、信任级别字典和上一次风险结果。
+*   **`get_display_name()`**: 返回个体的中英文显示名称。
+*   **`get_coords_for_plot(...)`**: 根据选择的坐标系类型（简化或综合）计算个体在三维图中的绘图坐标。
+*   **`_apply_boundary_effect(...)`**: 内部方法，用于实现维度值在接近0或10边界时的“软边界”效应，减缓变化速度。
+*   **`_calculate_delta_X(...)`**: 一系列内部方法，分别计算每个维度 (`b1_resource`, `s1_trustworthiness` 等) 在一个演化步骤中的变化量 (`delta`)。这些方法是模型核心算法的体现，包含了：
+    *   维度间的内部相互作用。
+    *   对风险项目结果的响应。
+    *   对邻居效应的整合。
+    *   对全局环境因素的考虑（间接通过 `evolve` 方法传递的参数）。
+*   **`_calculate_neighbor_effects(...)`**: 计算来自邻居网络的综合影响，包括：
+    *   资源竞争与合作（受信任度调节）。
+    *   应然维度（Y1, Y2, Y3）的社会对齐/传染（受自身声望/自信调节）。
+    *   社交维度（S1, S2）的社会规范压力。
+    *   信任动态（`self.trust_levels` 的更新）。
+    *   H2（创新）的信息共享（受信任度和邻居声望调节）。
+*   **`evolve(params, all_states_objects_dict, active_event_effects_on_self, global_env_factors)`**: 核心演化方法，执行一个时间步的逻辑：
+    1.  **风险项目评估与执行：** 根据H3, Y2, S2等决定是否尝试风险项目，计算投资、潜力、风险，并随机生成回报结果，直接影响B1, B2，并记录 `current_risk_outcome_this_step`。
+    2.  **计算全局平均值：** 如平均资源、平均可能性等，供Y3等维度参考。
+    3.  **计算邻居效应：** 调用 `_calculate_neighbor_effects`。
+    4.  **计算各维度Deltas：** 调用所有 `_calculate_delta_X` 方法，传入必要的参数（包括本轮的风险结果 `current_risk_outcome_this_step`）。
+    5.  **应用Deltas、噪声、事件效果、和裁剪：** 更新所有维度值，应用学习率、随机噪声、来自`EventManager`的事件效果（考虑个体韧性），并确保值在0-10范围内。
+    6.  **更新 `self.last_risk_outcome_factor`：** 为下一轮迭代做准备。
+*   **`record_history(...)`**: 记录当前绘图坐标到历史轨迹。
+*   **`clear_history()`**: 清空历史轨迹。
+*   **`to_dict()` / `from_dict()`**: 用于对象的序列化和反序列化，方便在Dash的 `dcc.Store` 中存储和传递。
+
+### 3. `Event` 类 和 `EventManager` 类
+
+这两个类共同构成了事件系统。
+
+*   **`Event`**: 定义单个事件的属性和行为：
+    *   `name` (事件名称), `trigger_type` (触发类型：概率性、全局条件性、个体条件性), `trigger_params` (触发参数), `target_selector` (目标选择逻辑), `effects` (效果列表), `duration` (持续时间), `one_time` (是否一次性)。
+    *   `check_trigger(...)`: 判断事件在本步骤是否触发（考虑全局环境对概率的修正）。
+    *   `select_targets(...)`: 根据选择器逻辑从所有状态点中选出受影响的目标。
+    *   `get_effects_for_target()`: 生成将应用于目标的具体效果数据（考虑效果值的随机波动）。
+*   **`EventManager`**: 管理所有事件的生命周期和执行：
+    *   `__init__(...)`: 加载事件定义列表。
+    *   `reset_events()`: 重置事件管理器状态（如清除已触发的一次性事件）。
+    *   `process_step(all_states_objects_dict, global_metrics, global_env_factors)`: 在每个演化步骤中被调用：
+        1.  检查所有已定义事件的触发条件。
+        2.  为已触发的事件选择目标。
+        3.  处理瞬时事件效果和持续性事件效果（通过 `active_timed_effects` 跟踪）。
+        4.  移除已触发的一次性事件。
+        5.  返回一个字典，其中包含本步骤需要应用到每个目标状态点的具体效果列表，以及事件触发的日志消息。
+
+### 4. 初始化数据
+
+此部分定义了程序启动时的初始配置：
+
+*   `initial_states_templates_gm452`: 包含多个预定义的状态点模板（字典列表），每个模板包含其中文名、英文ID和各个维度的初始值。
+*   `initial_states_obj_list_gm452`: 根据模板创建 `WorldState` 对象列表。
+*   `neighbor_config_gm452`: 定义状态点之间的初始邻居关系。
+*   `initial_world_states_store_data_gm452`: 将状态对象转换为字典，用于Dash `dcc.Store` 的初始数据。
+*   `default_evolution_params_gm452`: 一个包含模型所有演化参数的字典，包括：
+    *   全局参数：`learning_rate`, `noise_level`, `base_consumption` 等。
+    *   各种行为阈值：如风险尝试阈值、理想-现实差距阈值等。
+    *   `coefficients`: 一个嵌套字典，包含所有 `_calculate_delta_X` 方法中使用的具体系数 `k` 值，以及社会交互 `social_interactions` 的系数。**这部分是模型调优的核心。**
+    *   `plot_weights`: 用于计算综合坐标的绘图权重。
+*   `global_environment_factors_gm452`: 定义初始的全局环境因子。
+*   `event_definitions_gm452`: 事件定义列表，每个事件是一个字典，描述其属性。
+*   `event_manager`: `EventManager` 的全局实例。
+
+### 5. Dash 应用布局 (`app.layout`)
+
+使用 `dash.dcc` 和 `dash.html` 组件构建Web用户界面，主要包括：
+
+*   **标题和全局存储组件 (`dcc.Store`)**: 用于存储状态数据、演化参数、全局环境因子、事件日志等。
+*   **左侧控制面板**:
+    *   坐标系类型选择下拉框。
+    *   状态点选择下拉框。
+    *   **编辑面板 (`edit-panel-div`)**: 根据选定的状态点，动态生成所有维度的滑块，允许用户手动编辑。
+    *   **邻居信息 (`neighbor-info-div`) 和信任信息 (`trust-info-div`) 显示区域。**
+    *   **全局环境因子控制滑块。**
+    *   **动态演化控制**: 开始/暂停按钮、演化一步按钮、重置按钮、演化速度输入框、学习率和噪声水平滑块。
+    *   迭代步数显示。
+*   **右侧显示面板**:
+    *   **3D散点图 (`main-3d-scatter-plot`)**: 使用 `plotly.graph_objects.Scatter3d` 实时可视化所有状态点在三维空间中的位置及其历史轨迹。点的颜色和悬停文本提供额外信息。
+    *   **事件与状态日志文本框 (`event-log-textarea`)**: 显示事件触发信息和状态点内部的关键日志（如风险项目结果）。
+
+### 6. Dash 回调函数 (`@app.callback`)
+
+实现应用的交互逻辑和动态更新，主要包括：
+
+*   **更新下拉框和编辑面板**: 根据 `world-states-store` 和用户选择动态更新。
+*   **响应滑块修改**: 将用户对维度滑块、学习率、噪声、全局环境因子滑块的修改更新到相应的 `dcc.Store`。
+*   **演化控制**: 处理开始/暂停、步进、重置按钮的点击事件。
+*   **核心演化循环 (`run_evolution_step_advanced_gm452`)**:
+    *   由 `dcc.Interval` 或“演化一步”按钮触发。
+    *   获取当前所有状态数据、演化参数和全局环境因子。
+    *   反序列化状态数据为 `WorldState` 对象列表。
+    *   计算全局指标。
+    *   调用 `event_manager.process_step` 处理事件。
+    *   对每个 `WorldState` 对象调用其 `evolve` 方法，传入所需参数。
+    *   记录历史轨迹。
+    *   将更新后的状态对象序列化回字典，并更新 `world-states-store`。
+    *   更新UI上的迭代信息和事件日志。
+*   **更新3D图**: 当 `world-states-store` 或坐标系类型变化时，重新生成并更新3D散点图。
+*   **更新邻居/信任信息和事件日志显示**。
+
+## 如何运行
+
+1.  确保已安装必要的Python库：`dash`, `plotly`, `numpy`。
+    ```bash
+    pip install dash plotly numpy
+    ```
+2.  将代码保存为 `.py` 文件 (例如 `RX-GML.py`)。
+3.  在终端中运行：
+    ```bash
+    python RX-GML.py
+    ```
+4.  打开浏览器，访问 Dash 应用通常运行的地址 (例如 `http://127.0.0.1:8061/`，端口号可能因你的运行而异，请查看终端输出)。
+
+## 未来可能的扩展方向
+
+*   更细致的演化参数UI控制（允许编辑所有`k`系数）。
+*   动态网络结构的形成与演化。
+*   更复杂的群体动力学和制度层面影响。
+*   引入个体间的“记忆”机制，影响其对其他个体的信任和行为。
+*   高级数据记录与离线分析功能。
+*   用户自定义初始状态和事件。
+
+## 贡献与反馈
+
+欢迎对该模型提出任何改进建议、发现潜在的bug，或分享基于此模型的有趣发现。
+
+---
+
+希望这个模板能帮助你很好地组织项目说明！你可以根据需要添加更多细节，例如对特定算法决策的解释、参数选择的理由、或者你通过模型观察到的一些初步现象等。