Macromolecule Registration — Monomer Registration Requirements¶
Custom monomers can be added to the monomer library to extend the set of building blocks available for peptide registration. This page describes the requirements a monomer structure must satisfy to be accepted by the system, including polymer type, attachment point rules, leaving group chemistry, and structure constraints. For the validation errors raised when requirements are not met, see Validation errors.
Supported polymer types¶
Two polymer types are supported for custom monomer registration in this release:
- PEPTIDE — amino acid residues, including natural, non-natural, and modified amino acids
- CHEM — chemical modifiers, terminal capping groups, branching linkers, and protecting groups
Oligonucleotide monomer types (RNA BASE, SUGAR, LINKER) are not in scope for this release.
Attachment points¶
Attachment points define where a monomer bonds to adjacent units in a polymer chain. Each attachment point consists of an order (R1, R2, R3, …) and a leaving group — the atom or group that departs when the bond forms.
R-group ordering for PEPTIDE monomers¶
For PEPTIDE monomers, attachment point order has fixed meaning:
| Attachment point | Role |
|---|---|
| R1 | N-terminal bond — connects to the C-terminal attachment point (R2) of the preceding residue |
| R2 | C-terminal bond — connects to the N-terminal attachment point (R1) of the following residue |
| R3 and above | Side-chain bonds — used for cross-links and CHEM branches |
R1 and R2 must be assigned to the correct chemistry. Swapping them produces an inverted linkage direction, which results in incorrect structure assembly or export failure.
Minimum R-group requirements by role:
| Monomer role | Required attachment points |
|---|---|
| Internal backbone residue | R1 and R2 |
| N-terminal capping group (no incoming bond) | R2 only |
| C-terminal capping group (no outgoing bond) | R1 only |
| Branch or side-chain modifier on backbone | R3 or higher (R1 or R2 must also be present) |
A PEPTIDE monomer with no R1 or R2 is rejected at validation.
R-group ordering for CHEM monomers¶
No ordering constraints apply to CHEM monomers. Any combination of attachment point orders is accepted. Each attachment point identifier must be unique within a monomer — a monomer cannot define two attachment points with the same R-number (e.g. two R1s).
Side-chain attachment points (R3 and above)¶
When a PEPTIDE monomer includes side-chain attachment points (R3+), the following rules apply:
- The first side-chain attachment point must be exactly R3. R4 or higher without R3 is not permitted.
- Side-chain attachment points must be consecutive (no gaps). R3 and R5 without R4 is not permitted.
These rules apply to PEPTIDE monomers only. CHEM monomers have no constraints on attachment point order.
Leaving groups¶
Each attachment point must have a leaving group — the atom that departs when a bond forms with an adjacent monomer. Leaving groups must be a single atom (at most one heavy atom).
Three leaving atom types are recognised:
| Leaving atom | Symbol | Typical chemistry |
|---|---|---|
| Hydrogen | H | Amine N-H (R1 of backbone), thiol S-H |
| Hydroxyl | OH | Carboxylic acid C-OH (R2 of backbone), alcohol, phosphate |
| Fluoride | F | Fluorinated aromatic carbon |
The combination of attachment atom and leaving atom must match one of nine supported reactive-site patterns:
| Pattern | Attachment atom | Leaving group | Structural requirement |
|---|---|---|---|
| Amine | N | H | Saturated nitrogen; no adjacent carbonyl, sulfonyl, or phosphoryl group |
| Heteroaromatic amine | N | H | Nitrogen in an aromatic ring |
| Carboxylic acid | C | OH | Carbon adjacent to a C=O group |
| Anomeric | C | OH | Cyclic hemiacetal carbon |
| Alcohol (carbon-based) | C | OH | Saturated carbon; not carboxyl, not hemiacetal |
| Alcohol (oxygen-based) | O | H | Oxygen with one heavy carbon neighbour; no adjacent carbonyl |
| Thiol | S | H | Saturated sulfur with one carbon neighbour |
| Phosphate | P | OH | Phosphorus with exactly three single-bonded oxygens and one double-bonded oxygen |
| Fluorinated aromatic | C | F | Carbon in an aromatic ring |
For a standard backbone PEPTIDE monomer, R1 uses the amine pattern (N–H) and R2 uses the carboxylic acid pattern (C–OH with adjacent carbonyl).
A monomer with an attachment point that does not match any supported pattern cannot be exported from HELM to a molecular structure. The export fails with UnsupportedMacromoleculeExportException. A leaving group with more than one heavy atom is rejected at registration time.
Structure requirements¶
The following constraints apply to the molecular structure supplied for a monomer:
| Requirement | Details |
|---|---|
| Single connected fragment | Disconnected (multi-fragment) structures are not accepted |
| No query atoms | Atoms specified as SMARTS query atoms (e.g. [#6]) are not permitted |
| No query bonds | Query bond types are not permitted |
| No absolute stereochemistry flag | The absStereo flag must not be set on the structure |
| No bare R-atom | An R-atom with ID 0 (written as a bare R) is not supported; all R-atoms must carry an explicit numeric ID |
| Exactly one superatom S-group | The structure must contain exactly one superatom S-group defining the monomer abbreviation; zero or more than one are both rejected |
| Non-empty structure | The structure must contain at least one atom |
Standard SMILES features are accepted: aromatic notation, stereo bonds, and isotope labels.
Protecting groups¶
Protecting groups are registered as CHEM monomers. They are recognised during MOL-to-HELM conversion when a leaving-group S-group (LGRP class) in the input MOL file carries a label that matches an abbreviation in the monomer library.
Protecting group monomers typically have R1 only (a single attachment to the backbone nitrogen or a sidechain). The leaving atom at the attachment point is the hydrogen.
Worked examples¶
Backbone monomer — Alanine (A)¶
Alanine is a standard backbone PEPTIDE monomer with R1 (N-terminal) and R2 (C-terminal):
- R1: amino nitrogen, leaving atom = H → amine pattern
- R2: carboxyl carbon, leaving atom = OH → carboxylic acid pattern
SMILES (superatom form): [H]N[C@@H](C)C(O)=O
Terminal CHEM monomer — Acetyl (Ac)¶
Acetyl is a CHEM monomer used as an N-terminal capping group (R1 only):
- R1: carbonyl carbon, leaving atom = OH → carboxylic acid pattern
SMILES (superatom form): CC(=O)O
In a HELM string, Ac connects to the peptide via CHEM1,PEPTIDE1,1:R1-1:R1 — both the Ac R1 and the peptide N-terminal R1 lose their leaving groups to form the amide bond.
Validation errors¶
Compound Registration validates monomer structures at registration time. The table below lists the checks applied and the error raised when each check fails.
Structure and definition errors¶
| Scenario | Error type | Message |
|---|---|---|
| Abbreviation is missing | MISSING_ABBREVIATION | The abbreviation is missing. |
| Abbreviation is blank or whitespace | INVALID_ABBREVIATION | The abbreviation is empty or contains only whitespace. |
| Abbreviation contains invalid characters | INVALID_ABBREVIATION | The abbreviation '<abbrev>' contains invalid characters. Use only letters (A-Z, a-z), numbers (0-9), underscores (_), and hyphens (-). |
| Single-character abbreviation is not a letter | INVALID_ABBREVIATION | The abbreviation '<abbrev>' is invalid. Single-character abbreviations must be a letter (A-Z or a-z). |
| Abbreviation matches BILN multiplicity pattern | INVALID_ABBREVIATION | The abbreviation '<abbrev>' is invalid. It matches the BILN 'n x monomer abbreviation' pattern and would be ambiguous. |
| No polymer type set | MISSING_POLYMER_TYPE | The polymer type is missing. |
| No structure provided | MISSING_STRUCTURE | The molecular structure is required for <type> monomers but is missing. |
| Structure has no atoms | INVALID_STRUCTURE | The molecular structure for <type> contains no atoms. |
| Disconnected fragments | INVALID_STRUCTURE | The molecular structure for <type> contains multiple disconnected fragments. |
| Missing superatom S-group | INVALID_STRUCTURE | The structure for <type> is missing a Superatom S-group. |
| Multiple superatom S-groups | INVALID_STRUCTURE | The structure for <type> contains <n> Superatom S-groups, but exactly one is required. |
| Query atoms present | INVALID_STRUCTURE | The structure for <type> contains query atoms, which are not allowed. |
| Query bonds present | INVALID_STRUCTURE | The structure for <type> contains invalid bond types. Query bonds are not allowed. |
| Absolute stereo flag set | INVALID_STRUCTURE | Absolute stereochemistry (absStereo) flag is forbidden in monomer definitions. |
| Bare R-atom (ID 0) present | INVALID_STRUCTURE | The structure for <type> contains an R-atom with ID 0 (a simple 'R'), which is not supported. |
Attachment point errors¶
| Scenario | Error type | Message |
|---|---|---|
| PEPTIDE monomer has no R1 or R2 | MISSING_ATTACHMENT_POINT | The structure for PEPTIDE is missing required attachment points with order 1 or 2. |
| Side-chain attachment points do not start at R3 | INVALID_ATTACHMENT_POINT_ORDER | For <type>, if attachment points have order 3 or higher, the first one must be at order 3, but order <n> was found instead. |
| Side-chain attachment points have a gap | INVALID_ATTACHMENT_POINT_ORDER | For <type>, attachment points with order 3 or higher must be consecutive, but there is a gap between order <n> and order |
| Attachment point has no leaving group | MISSING_LEAVING_GROUP | A leaving group is missing at attachment point order <n> for <type>. |
| Leaving group has more than one heavy atom | INVALID_LEAVING_GROUP | The leaving group at attachment point order <n> for <type> has more than one heavy atom. Leaving groups must have at most one heavy atom. |
Limitations¶
- Inline SMILES monomers not supported. Monomers cannot be specified as inline SMILES within a HELM string. All monomers must be registered in the library before use.
- Oligonucleotide monomer types not in scope. RNA BASE, SUGAR, and LINKER polymer types are not supported for registration in this release.