From f82b1f2fae4b664577b551052d15bdd8e005686e Mon Sep 17 00:00:00 2001 From: Yanjie Huang Date: Tue, 8 Sep 2026 23:47:12 -0700 Subject: [PATCH 1/2] Polish README presentation and consolidate guide navigation --- README.md | 324 +++++++++++++++++++--------------------- fig/readme_overview.svg | 18 +++ 2 files changed, 173 insertions(+), 169 deletions(-) create mode 100644 fig/readme_overview.svg diff --git a/README.md b/README.md index 4c9d97f..a32657d 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,66 @@ -# EVA: A Long-Context Generative Foundation Model for Versatile RNA Design - -
- EVA -
- -[Paper](https://www.biorxiv.org/content/10.64898/2026.03.17.712398v1) · -[Model weights](https://huggingface.co/GENTEL-Lab/EVA) · -[OpenRNA data](https://huggingface.co/datasets/GENTEL-Lab/OpenRNA-v1-114M) · -[Website](https://evabio.net/) · [Apache-2.0 license](LICENSE) - -EVA is a generative RNA foundation model for sequence scoring and conditional -sequence modeling. The released model family includes a 1.4B-parameter -mixture-of-experts model with an 8,192-token context window, trained on OpenRNA v1. -This repository contains model code, command-line tools and paper reproduction + +

+ EVA — RNA foundation model +

+ +

EVA

+

A Long-Context Generative Foundation Model for Versatile RNA Design

+ +

+ Paper on bioRxiv + Models on Hugging Face + OpenRNA dataset + CPU checks on main + Apache 2.0 license +

+ +

+ Get started   ·   + Reproduce the paper   ·   + Documentation   ·   + Website   ·   + Cite EVA +

+ +EVA brings RNA sequence scoring and conditional sequence modeling into one +framework, with public model code, checkpoints and selected paper reproduction workflows. Model weights and large datasets are downloaded separately. -## Start here - -| I want to… | Start with | Requirements | -|---|---|---| -| Check a bundled result without a GPU | [CPU result recalculation](docs/REPRODUCTION.md#cpu-recalculate-stored-predictions) | Python 3.10/3.11 only | -| Run a benchmark from model weights | [135-sequence Milena example](docs/REPRODUCTION.md#gpu-run-the-complete-milena-benchmark) | Linux/NVIDIA GPU; Docker recommended | -| Use scoring or generation | [CLI guide](docs/USAGE.md) | Compatible GPU runtime and a checkpoint | -| Train or fine-tune | [Training workflow](docs/REPRODUCTION.md#training-and-fine-tuning) | Complete source checkout and GPU runtime | -| Find a paper result or comparison model | [Paper workflows](docs/PAPER_WORKFLOWS.md) | Requirements vary by workflow | - -## Quick Start - -Clone the repository and recalculate the bundled Milena benchmark metric: + +

+ 1.4B-parameter MoE flagship model; 8,192-token context window; trained on OpenRNA v1 +

+ + + +## Get started + + + + + + + +
+

01   Explore on CPU

+

Recalculate a bundled benchmark result from saved predictions.

+

Python 3.10 / 3.11 · No model download

+ Try the quick start → + 		+

02   Run on GPU

+

Score all 135 Milena sequences from a pinned EVA checkpoint.

+

Linux / NVIDIA GPU · Docker runtime

+ Run the benchmark → + 		+

03   Train & fine-tune

+

Start with a small training and checkpoint save/reload workflow.

+

Source checkout · Compatible GPU runtime

+ Explore training → +
+ +### Quick start + +A first result with Python's standard library: ```bash git clone https://github.com/GENTEL-Lab/EVA.git @@ -36,15 +69,25 @@ python3 scripts/reproduce_historical_benchmark.py \ --artifact-only --output results/milena_stored ``` -This standard-library-only example writes `report.json` and -`sequence_label_audit.csv` for all 135 stored predictions. The expected Spearman -correlation is **0.8360456283218484**, and the command returns 0. It recalculates -an archived result; the [GPU example](docs/REPRODUCTION.md#gpu-run-the-complete-milena-benchmark) -performs new model inference. Use a new output directory when rerunning. +**Expected:** 135 stored predictions, Spearman **0.8360456283218484**, exit code `0`. +The output directory contains `report.json` and `sequence_label_audit.csv`. +This recalculates an archived result; the GPU path below runs new inference. +Use a new output directory when rerunning. + + + +## Reproduce the paper -## Installation +The representative workflow connects **pinned checkpoint → 135 input sequences +→ new predictions → metrics & plots**. Inputs, model files and the scoring +protocol are bound to version and checksum records. -For model inference, build and enter the runtime from the repository root: + + +
+Run the GPU example · Environment setup and complete inference command + +From the repository root, build and enter the runtime **on the host**: ```bash mkdir -p checkpoint results @@ -53,14 +96,7 @@ docker run --rm -it --gpus device=0 --name eva-repro \ -v "$PWD":/eva -w /eva eva:local bash ``` -Then follow the GPU example below **inside the container**. Full setup, source -installation and HPC instructions are in [Installation](docs/INSTALLATION.md). - -## Reproducing the paper - -The complete representative example downloads a pinned public checkpoint, -checks its files, scores all 135 Milena sequences, calculates the metric and -writes diagnostic plots: +Then run **inside the container**: ```bash python scripts/download_reproduction_checkpoint.py \ @@ -69,150 +105,100 @@ python scripts/reproduce_milena.py \ --checkpoint checkpoint/EVA_1.4B_CLM --output results/milena_fresh ``` -Observed new-inference Spearman: **0.8394237924835843**; archived reference: -**0.8360456283218484**. The difference remains visible in the output and is not -an execution failure. Add `--strict-reference` only to request a nonzero exit -when comparison at the stored reference precision fails. Input, dependency, -scoring and plotting failures always remain errors. +See [Installation](docs/INSTALLATION.md) for source installs, runtime versions +and Singularity / Apptainer instructions. -The recorded A100 run scored the assay in about **12 seconds**, with **2.94 GiB** -peak PyTorch-allocated GPU memory. These are measurements for this example, -not minimum hardware requirements or estimates for other workloads; downloads, -loading, hashing and plotting add overhead. +
-- [Reproduction guide](docs/REPRODUCTION.md): commands, inputs, outputs and validation scope. -- [Reviewer requirements](docs/REVIEWER_REQUIREMENTS.md): six software requirements and supporting evidence. -- [Paper workflow coverage](docs/PAPER_WORKFLOWS.md): supported entry points and missing resources. -- [Validation and release status](docs/RELEASE_STATUS.md): dated evidence and publication state. +
+Expected results & measured runtime · Reference comparison, exit codes and hardware -## Model and data resources - -The [resource index](docs/RESOURCES.md) links checkpoints, OpenRNA and deposited -analysis data. The representative example fixes the model revision and SHA256 -checksums in its manifest. Historical competitor resources and available -execution entry points are listed in [comparison models](docs/OFFICIAL_MODEL_RESOURCES.md). - -## Repository layout +| Measurement | Recorded result | +|---|---| +| New-inference Spearman | **0.8394237924835843** | +| Archived reference | **0.8360456283218484** | +| Scoring time | About **12 seconds** for all 135 sequences | +| Peak PyTorch-allocated GPU memory | **2.94 GiB** | +| Environment | One NVIDIA A100-SXM4-80GB; batch size 1; pinned Docker runtime | + +Default mode returns `0` when inference, metrics and plots complete successfully. +The reference difference remains visible. Add `--strict-reference` to return `2` +when comparison at the stored reference precision fails. Input, dependency, +scoring and plotting failures remain errors in either mode. + +These are measurements for this example, not minimum hardware requirements +or estimates for other workloads. Downloads, loading, hashing and plotting +add overhead. A successful example does not establish reproduction of every +paper experiment. See [dated validation records](docs/RELEASE_STATUS.md). + +
+ +[Protocol & outputs](docs/REPRODUCTION.md)   ·   +[Paper workflow coverage](docs/PAPER_WORKFLOWS.md)   ·   +[Reviewer requirements](docs/REVIEWER_REQUIREMENTS.md) + + + +## Documentation + + + + + + + + + + + + + + + + + + + +
GuideWhat you will find
Using EVA →Scoring and generation, conditioning, batch configuration, and input/output formats.
Reproduction →CPU recalculation, GPU inference, training, and the scope of verified paper workflows.
Models & data →EVA checkpoints, OpenRNA, deposited analysis data, and historical comparison-model resources.
Development →Installation for contributors, tests, pull requests, and reproducible bug reports.
+ + +
+Repository map · Where the code and reproduction assets live | Directory | Contents | |---|---| | `eva/`, `tools/` | Model, tokenizer and inference CLIs | | `training/`, `finetune/`, `config/` | Training entry points and configurations | -| `scripts/` | Portable reproduction tools and shell entry points | -| `notebooks/` | Analysis notebooks and benchmark inputs | +| `scripts/`, `notebooks/` | Reproduction tools, analysis and benchmark inputs | | `reproduction/` | Versioned inputs, historical sources and validation records | | `docs/`, `tests/` | Guides and regression tests | -The Python wheel contains the importable model and CLI packages. Use the full +The wheel contains the importable model and CLI packages. Use the complete source checkout for training, notebooks and paper-reproduction inputs. -Historical sources under `reproduction/` are labeled separately from supported -entry points and may preserve old paths. +Historical sources under `reproduction/` are labeled separately and may preserve +old paths; use the documented entry points for current workflows. -## Development and support +
-See [CONTRIBUTING.md](CONTRIBUTING.md) for installation, tests and contribution -instructions. [Open an issue](https://github.com/GENTEL-lab/EVA/issues/new/choose) -with your commit, environment, command and error log when reporting a problem. -CPU checks run on pull requests and updates to main; GPU validation is recorded -separately and is not implied by a CPU check. + ## Citation -Software citation metadata are in [CITATION.cff](CITATION.cff). Cite the exact -Git commit used for your work and the paper linked above. The integrated -**1.2.0rc1** source is public on main; its formal release and archival code DOI -are pending. Existing data DOIs identify data deposits, not this code revision. - -## License - -Source code is released under [Apache-2.0](LICENSE). External datasets and -third-party checkpoints retain their own upstream terms. - -## Detailed guides and previous links - -The detailed reference has moved into the guides below. Existing README -section links remain available here. - - **Why Use EVA?** → [Open guide](docs/REPRODUCTION.md) - - **Key Modules** → [Open guide](docs/REPRODUCTION.md) - - **Our Journey with EVA Starts Here 👋** → [Open guide](docs/REPRODUCTION.md) - - **Option A: Local source install** → [Open guide](docs/REPRODUCTION.md) - - **Option B: Docker runtime** → [Open guide](docs/REPRODUCTION.md) - - **Option C: Singularity / Apptainer (HPC clusters)** → [Open guide](docs/REPRODUCTION.md) - - **Troubleshooting: Triton `undefined symbol: cuModuleGetFunction`** → [Open guide](docs/INSTALLATION.md#troubleshooting-triton-undefined-symbol-cumodulegetfunction) - - **Pre-release smoke test** → [Open guide](docs/INSTALLATION.md#pre-release-smoke-test) - - **Model download** → [Open guide](docs/REPRODUCTION.md) - - **Release and Versioning** → [Open guide](docs/RELEASE_STATUS.md) - - **Repository Paths** → [Open guide](docs/REPRODUCTION.md) - - **Condition Control** → [Open guide](docs/USAGE.md#condition-control) - - **RNA Types** → [Open guide](docs/USAGE.md#rna-types) - - **Species/Lineage** → [Open guide](docs/USAGE.md#specieslineage) - - **Generation** → [Open guide](docs/USAGE.md#generation) - - **CLM** → [Open guide](docs/USAGE.md#clm) - - **Unconditional Generation** → [Open guide](docs/USAGE.md#unconditional-generation) - - **Conditional Generation** → [Open guide](docs/USAGE.md#conditional-generation) - - **Continuation Mode** → [Open guide](docs/USAGE.md#continuation-mode) - - **GLM** → [Open guide](docs/USAGE.md#glm) - - **Unconditional Infilling** → [Open guide](docs/USAGE.md#unconditional-infilling) - - **Conditional Infilling** → [Open guide](docs/USAGE.md#conditional-infilling) - - **Span Parameters** → [Open guide](docs/USAGE.md#span-parameters) - - **Sampling Parameters** → [Open guide](docs/USAGE.md#sampling-parameters) - - **Scoring** → [Open guide](docs/USAGE.md#scoring) - - **RNA Mode** → [Open guide](docs/USAGE.md#rna-mode) - - **Protein Mode** → [Open guide](docs/USAGE.md#protein-mode) - - **Directed Evolution** → [Open guide](docs/USAGE.md#directed-evolution) - - **Usage** → [Open guide](docs/USAGE.md#usage) - - **Key Parameters** → [Open guide](docs/USAGE.md#key-parameters) - - **Batch Processing with YAML** → [Open guide](docs/USAGE.md#batch-processing-with-yaml) - - **Generation Config Example** → [Open guide](docs/USAGE.md#generation-config-example) - - **Scoring Config Example** → [Open guide](docs/USAGE.md#scoring-config-example) - - **Running** → [Open guide](docs/USAGE.md#running) - - **Input/Output Formats** → [Open guide](docs/USAGE.md#inputoutput-formats) - - **Input — FASTA** → [Open guide](docs/USAGE.md#input--fasta) - - **Output — Generation (FASTA)** → [Open guide](docs/USAGE.md#output--generation-fasta) - - **Output — Scoring (JSON)** → [Open guide](docs/USAGE.md#output--scoring-json) +Cite the paper and the exact Git commit used in your work. Software citation +metadata are available in [CITATION.cff](CITATION.cff). - **Output — Directed Evolution (FASTA)** → [Open guide](docs/USAGE.md#output--directed-evolution-fasta) +The **1.2.0rc1** source is public on main; its formal release and archival code +DOI are pending. Existing data DOIs identify data deposits. See +[validation & release status](docs/RELEASE_STATUS.md) for the current scope. - **Data Availability** → [Open guide](docs/RESOURCES.md) + - **Model & Environment** → [Open guide](docs/RESOURCES.md) +--- - **Experiment & Benchmark Data** → [Open guide](docs/RESOURCES.md) +

+ Apache-2.0 license   ·   + Contribute   ·   + Report an issue   ·   + EVA website +

+

External datasets and third-party checkpoints retain their upstream terms.

diff --git a/fig/readme_overview.svg b/fig/readme_overview.svg new file mode 100644 index 0000000..79ea813 --- /dev/null +++ b/fig/readme_overview.svg @@ -0,0 +1,18 @@ + + EVA at a glance + A 1.4 billion parameter mixture-of-experts flagship model, an 8,192-token context window, and OpenRNA v1 pretraining data. + + + + MODEL + 1.4B + Mixture-of-experts flagship + CONTEXT + 8,192 + Tokens per context window + DATA + OpenRNA + Pretrained on OpenRNA v1 + + + From 4b95d9d8940458424cb1b255c6ada53f3cc04916 Mon Sep 17 00:00:00 2001 From: Yanjie Huang Date: Tue, 8 Sep 2026 23:49:33 -0700 Subject: [PATCH 2/2] Keep documentation labels on one line --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a32657d..140f19c 100644 --- a/README.md +++ b/README.md @@ -142,7 +142,7 @@ paper experiment. See [dated validation records](docs/RELEASE_STATUS.md). ## Documentation - +
GuideWhat you will find
GuideWhat you will find
Using EVA → Scoring and generation, conditioning, batch configuration, and input/output formats.