Add Readme and visualization (#1)

- Add Readme and visualization (07adacdd4686cb3f4a266262fdaa66dc90e6a774)


Co-authored-by: Maxime Seince <[email protected]>

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+abbfn2_overview.png filter=lfs diff=lfs merge=lfs -text

README.md

@@ -0,0 +1,131 @@
+# AbBFN2: A flexible antibody foundation model based on Bayesian Flow Networks
+
+Welcome to the inference code of AbBFN2, a state-of-the-art model for antibody sequence generation.
+
+## Overview
+
+AbBFN2 is a generative antibody foundation model trained on a rich dataset of paired antibody sequences alongside their genetic and biophysical metadata. This allows for a unified modelling of diverse data sources and flexible conditional generation at inference time.
+AbBFN2 leverages the Bayesian Flow Network (BFN) framework, which models distributions over data rather than the data itself, making it suitable for both discrete (sequences, gene labels) and continuous (biophysical properties) data. 
+
+At inference, AbBFN2 can concurrently generate all 45 data modes. By conditioning on arbitrary combinations of information, the model can handle a variety of tasks without task-specific training.
+
+![AbBFN2 Overview](abbfn2_overview.png)
+
+## Prerequisites
+- Repo cloned on your machine. (insert link of the official repo)
+- Docker installed on your system
+- Sufficient computational resources (TPU/GPU recommended)
+
+## Installation
+
+### Hardware Configuration
+First, configure your accelerator in the Makefile:
+```bash
+ACCELERATOR = GPU  # Options: CPU, TPU, or GPU
+```
+
+Note: Multi-host inference is not supported in this release. Please use single-host settings only.
+
+### Building the Docker Image - Windows/Linux
+Run the following command to build the AbBFN2 Docker image:
+```bash
+make build
+```
+This process typically takes 5-20 minutes depending on your hardware.
+
+### Building the Virtual Envrionment - MacOS
+Run the following commands to build the AbBFN2 virtual environment:
+```bash
+conda env create -f environment.yaml
+```
+Please make sure you activate the environment before running the scripts.
+
+
+## Usage
+
+AbBFN2 supports three main generation modes, each with its own configuration file in the `experiments/configs/` directory.
+
+### 1. Unconditional Generation
+Generate novel antibody sequences without any constraints.
+
+Configuration (`unconditional.yaml`):
+```yaml
+cfg:
+  sampling:
+    num_samples_per_batch: 10   # Number of sequences per batch
+    num_batches: 1              # Number of batches to generate
+  sample_fn:
+    num_steps: 300              # Number of sampling steps (recommended: 300-1000)
+```
+
+Run:
+```bash
+make unconditional
+```
+
+### 2. Inpainting
+Generate antibody sequences conditioned on specific CDR regions.
+
+Configuration (`inpaint.yaml`):
+```yaml
+cfg:
+  input:
+    num_input_samples: 2        # Number of input samples
+    dm_overwrites:              # Specify values of the data modes
+      h_cdr1_seq: GYTFTSHA
+      h_cdr2_seq: ISPYRGDT
+      h_cdr3_seq: ARDAGVPLDY
+  sampling:
+    inpaint_fn:
+      num_steps: 300-1000       # Number of sampling steps (recommended: 300-1000)
+    mask_fn:
+      data_modes:               # Specify which regidata modes to condition on
+        - "h_cdr1_seq"
+        - "h_cdr2_seq"
+        - "h_cdr3_seq"
+```
+
+Run:
+```bash
+make inpaint
+```
+
+### 3. Sequence Humanization
+Convert non-human antibody sequences into humanized versions.
+
+Configuration (`humanization.yaml`):
+```yaml
+cfg:
+  input:
+    l_seq: "EVKLQQSGPGLVTPSQSLSITCTVSGFSLSDYGVHWVRQSPGQGLEWLGVIWAGGGTNYNSALMSRKSISKDNSKSQVFLKMNSLQADDTAVYYCARDKGYSYYYSMDYWGQGTSVTVSS"
+    h_seq: "DIETLQSPASLAVSLGQRATISCRASESVEYYVTSLMQWYQQKPGQPPKLLIFAASNVESGVPARFSGSGSGTNFSLNIHPVDEDDVAMYFCQQSRKYVPYTFGGGTKLEIK"
+  sampling:
+    recycling_steps: 10         # Number of recycling steps (recommended: 5-12)
+    inpaint_fn:
+      num_steps: 500            # Number of sampling steps (recommended: 300-1000)
+```
+
+Run:
+```bash
+make humanization
+```
+
+## Citation
+If you use AbBFN2 in your research, please cite our work:
+
+```text
+@article {,
+	author = {},
+	title = {AbBFN2: A flexible antibody foundation model based on Bayesian Flow Networks},
+	elocation-id = {},
+	year = {},
+	doi = {},
+	publisher = {},
+	URL = {},
+	eprint = {},
+	journal = {}
+}
+```
+
+## License
+[License information to be added]