PerioGT

https://github.com/wuyuhui-zju/periogt
Admin
PerioGT is a periodicity-aware foundation model and deep learning framework for polymer property...
Tokens:4,325
Snippets:36
Trust Score:4.6
License:MIT
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### Run finetuning script

Source: https://github.com/wuyuhui-zju/periogt/blob/main/README.md

Launches end-to-end fine-tuning using the provided example script. Modify the script to use your own dataset.

```bash
bash finetune_example.sh
```

--------------------------------

### Launch pretraining with torch.distributed.run

Source: https://github.com/wuyuhui-zju/periogt/blob/main/README.md

Starts periodicity-aware self-supervised pretraining on multiple GPUs. Distributed training is enabled via CUDA_VISIBLE_DEVICES, --nproc_per_node, --nnodes, and --n_devices. The --backbone option supports 'light' and 'graphgps'. Pretraining takes about 50 hours on three RTX 4090 GPUs.

```bash
CUDA_VISIBLE_DEVICES=0,1,2 python -u -m torch.distributed.run \
    --nproc_per_node=3 \
    --nnodes=1 \
    pretrain.py \
    --save_path ../checkpoints/pretrained/light \
    --n_threads 8 \
    --n_devices 3 \
    --config base \
    --backbone light \
    --n_steps 100000 \
    --data_path ../datasets/pretrain/
```

--------------------------------

### Example dataset CSV format

Source: https://github.com/wuyuhui-zju/periogt/blob/main/README.md

Shows the required two-column CSV format (smiles,value) for a polymer property dataset, using dielectric constant as an example.

```csv
smiles,value
*CC(*)C,2.61
*CC(*)F,3.36
*CO*,3.72
...
```

--------------------------------

### Finetune pretrained model with finetune.py

Source: https://github.com/wuyuhui-zju/periogt/blob/main/README.md

Finetunes the pretrained encoder on a downstream task. The --mode flag selects between 'finetune' (end-to-end) and 'freeze' (freeze encoder). Use --save and --save_suffix to enable checkpoint saving. A good starting learning rate is --lr 5e-4, but tuning may be needed.

```bash
python finetune.py \
    --config base \
    --backbone light \
    --mode finetune \
    --model_path ../checkpoints/pretrained/light/base.pth \
    --dataset eps \
    --weight_decay 0 \
    --dropout 0.05 \
    --lr 1e-4 \
    --device cuda
```

--------------------------------

### Activate the PerioGT conda environment

Source: https://github.com/wuyuhui-zju/periogt/blob/main/README.md

Activates the conda environment named 'PerioGT'. Requires Anaconda or Miniconda to be installed beforehand.

```bash
conda activate PerioGT
```

--------------------------------

### Run feature extraction script

Source: https://github.com/wuyuhui-zju/periogt/blob/main/README.md

Extracts polymer embeddings from the pretrained model using the example dataset. Outputs features.npz.

```bash
bash extract_features_example.sh
```

--------------------------------

### Prepare finetuning dataset with prepare_ft_dataset.py

Source: https://github.com/wuyuhui-zju/periogt/blob/main/README.md

Prepares a downstream dataset (e.g., eps) for finetuning. Requires a pretrained checkpoint at --model_path. The --use_prompt flag enables periodicity prompt encoding. The dataset name must match a folder under datasets/.

```bash
python prepare_ft_dataset.py \
    --dataset eps \
    --device cuda \
    --config base \
    --backbone light \
    --model_path ../checkpoints/pretrained/light/base.pth \
    --data_path ../datasets \
    --use_prompt
```

--------------------------------

### Create conda environment for PerioGT

Source: https://github.com/wuyuhui-zju/periogt/blob/main/README.md

Navigates into the project directory and creates the conda environment from the environment.yml file. This may take a few minutes.

```bash
cd PerioGT
conda env create
```

--------------------------------

### Create checkpoint directory

Source: https://github.com/wuyuhui-zju/periogt/blob/main/README.md

Creates the directory structure for storing the pretrained model checkpoint.

```bash
mkdir -p checkpoints/pretrained/light/
```

--------------------------------

### Prepare pretraining dataset with prepare_pt_dataset.py

Source: https://github.com/wuyuhui-zju/periogt/blob/main/README.md

Run from the PerioGT_common/scipts/ directory. Place a CSV file with a 'smiles' column in datasets/pretrain/ first. The --n_rus flag controls the number of repeating units for descriptor calculation (e.g., 3, 6, or 9).

```bash
python prepare_pt_dataset.py --data_path ../datasets/pretrain/ --dataset YOUR_PRETRAIN_DATASET --n_jobs 32 --n_rus 3
```

--------------------------------

### Evaluate finetuned model with evaluation.py

Source: https://github.com/wuyuhui-zju/periogt/blob/main/README.md

Evaluates a finetuned model using a saved checkpoint. The --model_path should point to the checkpoint file (e.g., best_model.pth). Place downloaded finetuned checkpoints in checkpoints/eps/ for direct evaluation.

```bash
python evaluation.py \
    --config base \
    --backbone light \
    --model_path ../checkpoints/eps/best_model.pth \
    --dataset eps \
    --dropout 0 \
    --device cuda
```

--------------------------------

### Dataset directory structure

Source: https://github.com/wuyuhui-zju/periogt/blob/main/README.md

Illustrates the expected directory layout for organizing multiple polymer datasets under the datasets/ folder.

```text
datasets/
├── eps/
│   └── eps.csv
├── YOUR_DATASET/
│   └── YOUR_DATASET.csv
└── ...
```

--------------------------------

### Clone the PerioGT repository

Source: https://github.com/wuyuhui-zju/periogt/blob/main/README.md

Clones the PerioGT repository from GitHub. Run this command first to obtain the project source code.

```bash
git clone https://github.com/wuyuhui-zju/PerioGT.git
```

--------------------------------

### Split dataset script

Source: https://github.com/wuyuhui-zju/periogt/blob/main/README.md

Runs the dataset splitting script to generate a random 72/8/20 train/val/test split saved as split.pkl.

```bash
python split_dataset.py --dataset YOUR_DATASET
```

--------------------------------

### PerioGT project directory structure

Source: https://github.com/wuyuhui-zju/periogt/blob/main/README.md

Shows the top-level folder layout of the PerioGT project, including core implementation, copolymer extension, and homopolymer extension with additional information.

```text
├── PerioGT_common/          # Core implementation (including pretraining)
│   ├── checkpoints/         # Pretrained and finetuned model weights
│   ├── data/                # Data processing functions
│   ├── datasets/            # Raw and processed dataset files
│   ├── models/              # Model architectures
│   ├── scripts/             # Scripts for launching training and evaluation
│   ├── trainer/             # Training and evaluation logic (Trainer, Evaluator, etc.)
│   └── utils/               # Utility functions
├── PerioGT_copolym/         # Extension for copolymer property prediction
└── PerioGT_with_cond/       # Extension for homopolymers with additional information
```

--------------------------------

### BibTeX citation for PeriOGT paper

Source: https://github.com/wuyuhui-zju/periogt/blob/main/README.md

Use this BibTeX entry to cite the PeriOGT paper in academic work. The entry references the paper by Wu et al. published in Nature Computational Science, volume 5, pages 1214-1226, year 2025.

```bibtex
@article{wu2025periodicity,
  title={Periodicity-aware deep learning for polymers},
  author={Wu, Yuhui and Wang, Cong and Shen, Xintian and Zhang, Tianyi and Zhang, Peng and Ji, Jian},
  journal={Nature Computational Science},
  volume={5},
  pages={1214--1226},
  year={2025},
  publisher={Nature Publishing Group US New York}
}
```
Tokens:
Raw