pymdp 项目教程

1. 项目介绍

pymdp 是一个用于模拟马尔可夫决策过程（Markov Decision Process, MDP）中主动推理（Active Inference）的 Python 实现。主动推理是一种基于自由能原理（Free Energy Principle）的计算框架，旨在模拟智能体在不确定环境中如何通过学习和推理来最大化其预期效用。

该项目的主要目标是提供一个易于使用的工具包，帮助研究人员和开发者理解和实现主动推理算法。pymdp 的核心功能包括构建和模拟主动推理智能体，计算后验信念，推断策略，以及采样动作。

2. 项目快速启动

安装

要使用 pymdp，首先需要通过 pip 安装该包。建议在虚拟环境中进行安装，以避免依赖冲突。

pip install inferactively-pymdp

使用示例

以下是一个简单的示例，展示了如何使用 pymdp 创建一个主动推理智能体，并进行状态推断和策略推断。

import pymdp
from pymdp import utils
from pymdp.agent import Agent

# 定义观察模态维度、隐藏状态因子和控制状态因子
num_obs = [3, 5]  # 观察模态维度
num_states = [3, 2, 2]  # 隐藏状态因子维度
num_controls = [3, 1, 1]  # 控制状态因子维度

# 创建感官似然矩阵（A 矩阵）和转移似然矩阵（B 矩阵）
A_matrix = utils.random_A_matrix(num_obs, num_states)
B_matrix = utils.random_B_matrix(num_states, num_controls)

# 创建均匀偏好向量（C 向量）
C_vector = utils.obj_array_uniform(num_obs)

# 实例化一个主动推理智能体
my_agent = Agent(A=A_matrix, B=B_matrix, C=C_vector)

# 给智能体一个随机观察，并获取优化后的后验信念
observation = [1, 4]  # 观察的索引列表
qs = my_agent.infer_states(observation)  # 获取隐藏状态的后验信念

# 进行主动推理，获取策略后验和每个策略的负预期自由能
q_pi, neg_efe = my_agent.infer_policies()

# 采样一个动作
action = my_agent.sample_action()

3. 应用案例和最佳实践

应用案例：知识链任务

pymdp 的一个典型应用案例是模拟知识链任务（Epistemic Chaining Task）。在这个任务中，智能体（例如，一只寻找食物的老鼠）通过一系列线索来揭示隐藏奖励的位置。主动推理智能体通过最大化信息披露（即好奇心）来自然地探索线索序列，最终以最少的移动次数找到隐藏的奖励。

最佳实践

• 使用虚拟环境：建议在虚拟环境中安装和运行 pymdp，以避免依赖冲突。
• 参考官方文档：pymdp 的官方文档提供了详细的教程和示例，建议新用户从这些资源开始学习。
• 参与社区：pymdp 是一个活跃的开源项目，鼓励用户参与贡献和讨论。

4. 典型生态项目

pymdp 作为主动推理领域的开源工具，与其他相关项目形成了良好的生态系统。以下是一些典型的生态项目：

• SPM（Statistical Parametric Mapping）：pymdp 中的许多低级数学操作是基于 SPM 的 MATLAB 实现。SPM 是一个广泛使用的神经影像分析工具包。
• NumPy：pymdp 依赖于 NumPy 进行高效的数值计算，NumPy 是 Python 科学计算的核心库。
• Jupyter Notebook：pymdp 的官方文档和教程主要以 Jupyter Notebook 的形式提供，方便用户交互式学习和实验。

通过这些生态项目的支持，pymdp 能够提供强大的功能和灵活的使用方式，满足不同用户的需求。