renkin 0.15.0

Ultra-fast retrosynthesis engine for computer-aided synthesis planning (CASP) — pure Rust, WASM-ready, Python bindings via PyO3
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90

# Contributing to RENKIN

Thank you for your interest in contributing! RENKIN is a Pure Rust retrosynthesis engine and welcomes contributions of all kinds.

## Ways to Contribute

| Type | Examples |
|---|---|
| 🧪 **Reaction rules** | Add new SMIRKS retro-rules, fix incorrect disconnections |
| 🗂️ **Building blocks** | Extend the commercial reagent database |
| 🐛 **Bug reports** | Incorrect routes, wrong SMILES output, panics |
| ✨ **Features** | New CLI flags, API improvements |
| 📖 **Documentation** | Fix typos, improve examples, add translations |
| 🧬 **Benchmarks** | New test sets, external database integration |

## Setup

```bash
git clone https://github.com/kent-tokyo/renkin.git
cd renkin
cargo build          # debug build
cargo test           # run all 57 unit tests
cargo clippy -- -D warnings   # lint
cargo fmt --check              # format check
```

## Adding a Reaction Rule

Reaction rules live in `src/chem_env.rs` inside `default_rules()`.

**SMIRKS-based rule** (most rules):
```rust
RetroRule {
    name: "your_reaction_retro".to_string(),
    smirks: "[Product:1]>>[Reactant1:2].[Reactant2:3]".to_string(),
    weight: 1.0,
    required_elements: 0,  // or use elem_mask_from_smirks() result
},
```

**Graph-based rule** (for reactions where SMIRKS leaks, e.g. Suzuki):
```rust
RetroRule {
    name: "your_graph_rule".to_string(),
    smirks: String::new(),   // empty → dispatches to apply_retro match arm
    weight: 1.0,
    required_elements: 0,
},
```
Then add a match arm in `apply_retro()` and implement the graph traversal function.

**Tips:**
- Use [Daylight SMIRKS](https://www.daylight.com/dayhtml/doc/theory/theory.smirks.html) notation
- Test your rule with `cargo test` — add a test in `src/chem_env.rs #[cfg(test)]`
- `required_elements` is a u64 bitmask: set bits for elements that MUST appear in the target

## Adding Building Blocks

The default set is `DEFAULT_BUILDING_BLOCKS` in `src/lib.rs` (canonical SMILES strings).

For large sets, users supply `--building-blocks <file>` — no code change needed.

## Running the Full Benchmark

```bash
cargo build --release
bash scripts/run_benchmark_chunks.sh \
    data/uspto50k_test.smi \
    data/templates_extracted_5000.smi \
    data/bench_chunks_my_change \
    5 100
```

## Pull Request Guidelines

1. Run `cargo fmt` and `cargo clippy -- -D warnings` before submitting
2. Add a test for new rules or features
3. Update `CHANGELOG.md` under `[Unreleased]`
4. Keep PRs focused — one feature/fix per PR

## Reporting Bugs

Use [GitHub Issues](https://github.com/kent-tokyo/renkin/issues) and include:
- SMILES of the target molecule
- Expected vs. actual output
- RENKIN version (`renkin --version` or `cargo pkgid`)

## License

By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).