Data and code for, "Large language models perform molecular design"

# Codes and data for "Large language models design sequence-defined macromolecules via evolutionary optimization"

This repository contains codes and data files for the manuscript, frozen at the time of submission.

# Codes

## LLM codes

- `run_claude.py` - the routine for performing LLM-based rollouts; intended for command line execution using argparse

- `message_utils.py` - utilities for constructing and parsing messages for LLM I/O

- `model_utils.py` - lightweight utilities for retrieving formatted predictions from the RNN ensemble

- `target_defs.py` - defines the sequence, locations, and natural language descriptions of the target structures

- `ask_about_oracle.ipynb` - asks the LLM to speculate about the nature of the optimization task

## other algorithms

- `active_learning.ipynb` - use EI acquisition with RF surrogate to label new sequences; includes an unused tokenization scheme

- `evolutionary_algorithm.ipynb` - use DEAP library to perform evolutionary optimization

- `random_sampling.ipynb` - sample sequences randomly from all possible sequences

## postprocessing

- `process_aggregated_logs.py` - reads data from the raw log files and prepares them for visualization

- `process_sample_rollouts.py` - reads data from the raw log files and prepares individual rollouts

## visualization

- `figure1b.ipynb` - renders panel b of Fig. 1

- `figure1efg.ipynb` - renders the last row of Fig. 1 (panels e-g)

- `figure2.ipynb` - renders all of Fig. 2

# Data files

- `prompts/`

- `prompt-scientific-v4.yml` - the full text of the scientific prompt, to be read by `run_claude.py`

- `prompt-oracle-v4.yml` - the full text of the oracle prompt, to be read by `run_claude.py`

- `models/` - the TorchScript RNN models used to make predictions

- `data/`

- `embeddings` - calculated embeddings for a collection of sequences from our prior work

- `llm-logs` - the raw logs obtained from the LLM (other algorithms made to look like the LLM logs after the fact)

- `all-rollouts-kltd.csv` - postprocessed logs for all the rollouts using the "top $k < d^*$" metric

- `all-rollouts-topkd.csv` - postprocessed logs for all the rollouts using the "mean $d$ for top $k$" metric

- `sample-rollout-membranes-x-3.csv` - postprocessed logs for a single rollout replica, `x` = each algorithm type

- `snapshots` - png snapshots of MD simulation results at different locations in the manifold

# 《基于进化优化的大语言模型（Large Language Model）设计序列定义型大分子》配套代码与数据集
本仓库包含对应投稿手稿的代码与数据文件，版本固定为投稿提交时的状态。

# 代码部分

## 大语言模型相关代码
- `run_claude.py`：用于执行基于大语言模型的推演流程，支持通过argparse在命令行中运行
- `message_utils.py`：用于构建与解析大语言模型输入输出消息的工具函数集
- `model_utils.py`：用于从循环神经网络（Recurrent Neural Network, RNN）集成模型中获取格式化预测结果的轻量工具函数集
- `target_defs.py`：定义目标结构的序列、位点与自然语言描述信息
- `ask_about_oracle.ipynb`：用于提示大语言模型推演优化任务本质的交互式笔记本

## 其他算法实现
- `active_learning.ipynb`：结合期望改善（Expected Improvement, EI）采样准则与随机森林（Random Forest, RF）代理模型实现新序列标注的交互式笔记本，包含一套未启用的分词方案
- `evolutionary_algorithm.ipynb`：基于DEAP库实现进化优化的交互式笔记本
- `random_sampling.ipynb`：从所有可能序列空间中随机采样序列的交互式笔记本

## 后处理模块
- `process_aggregated_logs.py`：读取原始日志文件中的数据并预处理为可可视化格式
- `process_sample_rollouts.py`：读取原始日志文件中的数据并预处理为单条推演流程的格式

## 可视化模块
- `figure1b.ipynb`：用于渲染图1的(b)子图
- `figure1efg.ipynb`：用于渲染图1的最后一行（即(e)-(g)子图）
- `figure2.ipynb`：用于渲染整张图2

# 数据文件部分

- `prompts/` 目录
- `prompt-scientific-v4.yml`：科学提示词完整文本，供`run_claude.py`读取使用
- `prompt-oracle-v4.yml`：神谕提示词完整文本，供`run_claude.py`读取使用
- `models/` 目录：用于生成预测结果的TorchScript格式循环神经网络模型
- `data/` 目录
- `embeddings`：本研究前期工作中部分序列的计算得到的嵌入向量
- `llm-logs`：从大语言模型获取的原始日志文件（其余算法的日志后续被处理为与大语言模型日志格式一致）
- `all-rollouts-kltd.csv`：采用“前$k < d^*$”指标的所有推演流程的后处理日志
- `all-rollouts-topkd.csv`：采用“前$k$个样本的平均$d$”指标的所有推演流程的后处理日志
- `sample-rollout-membranes-x-3.csv`：单条推演复现的后处理日志，其中`x`代表各算法类型
- `snapshots`：流形空间不同位置的分子动力学（Molecular Dynamics, MD）模拟结果png快照