### Clone and install ColBuilder

Source: https://github.com/graeter-group/colbuilder/blob/main/README.md

Download the repository and install the package.

```bash
git clone git@github.com:graeter-group/colbuilder.git
cd colbuilder
pip install .
```

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

### Common Configuration Examples

Source: https://github.com/graeter-group/colbuilder/blob/main/docs/configuration.md

Examples of common ColBuilder configurations.

```APIDOC
### Basic Human Collagen Microfibril
```yaml
species: "homo_sapiens"
sequence_generator: true
geometry_generator: true
crosslink: true
fibril_length: 60.0
contact_distance: 20
n_term_type: "HLKNL"
c_term_type: "HLKNL"
n_term_combination: "9.C - 947.A"
c_term_combination: "1047.C - 104.C"
```

### Bovine Collagen with Trivalent Crosslinks
```yaml
species: "bos_taurus"
sequence_generator: true
geometry_generator: true
crosslink: true
n_term_type: "PYD"
c_term_type: "PYD"
n_term_combination: "9.C - 5.B - 942.B"
c_term_combination: "1046.C - 1046.A - 103.C"
fibril_length: 80.0
contact_distance: 20
```
```

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

### Install ColBuilder

Source: https://github.com/graeter-group/colbuilder/blob/main/docs/user_guide.md

Install the package using pip.

```bash
pip install .
```

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

### Install PyMOL and Dependencies

Source: https://github.com/graeter-group/colbuilder/blob/main/docs/user_guide.md

Install PyMOL and specific library versions if needed.

```bash
conda install conda-forge::pymol-open-source
```

```bash
conda install -c conda-forge libnetcdf==4.7.3
```

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

### Install UCSF Chimera

Source: https://github.com/graeter-group/colbuilder/blob/main/docs/user_guide.md

Make the downloaded installer executable and run it.

```bash
chmod +x chimera*.bin
./chimera*.bin
```

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

### Install MUSCLE

Source: https://github.com/graeter-group/colbuilder/blob/main/docs/user_guide.md

Install the MUSCLE sequence alignment tool.

```bash
conda install muscle
```

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

### Set Up Development Environment

Source: https://github.com/graeter-group/colbuilder/blob/main/CONTRIBUTING.md

Creates a dedicated Conda environment and installs the package in editable mode.

```bash
conda create -n colbuilder-dev python=3.9
conda activate colbuilder-dev
pip install -e .
```

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

### Install ColBuilder

Source: https://github.com/graeter-group/colbuilder/blob/main/docs/examples/colbuilder.md

Clone the ColBuilder repository and install dependencies using pip.

```bash
git clone https://github.com/graeter-group/colbuilder.git
cd colbuilder
pip install -e .
```

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

### Example Combined Mode Configuration

Source: https://github.com/graeter-group/colbuilder/blob/main/README.md

Demonstrates how to enable multiple ColBuilder modes (sequence generation, geometry generation, topology generation, and crosslink replacement) within a single configuration file for a combined workflow.

```yaml
# Example combination
sequence_generator: true
geometry_generator: true         # (optional)
topology_generator: true         # (optional)
replace_bool: true               # (optional)
```

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

### Verify Installation

Source: https://github.com/graeter-group/colbuilder/blob/main/docs/user_guide.md

Check that the ColBuilder command-line interface is accessible.

```bash
colbuilder --help
```

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

### Configure Multiple Force Field Topologies

Source: https://github.com/graeter-group/colbuilder/blob/main/docs/examples/example4/Readme.md

Example configuration files and execution commands for generating both atomistic and coarse-grained topologies.

```yaml
# config_amber.yaml
force_field: "amber99"
# ... rest of config
```

```yaml
# config_martini.yaml
force_field: "martini3"
# ... rest of config
```

```bash
colbuilder --config_file config_amber.yaml
colbuilder --config_file config_martini.yaml
```

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

### Install PyMOL dependency

Source: https://github.com/graeter-group/colbuilder/blob/main/README.md

Install the open-source version of PyMOL via Conda.

```bash
conda install conda-forge::pymol-open-source
```

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

### Species-Specific Configuration

Source: https://github.com/graeter-group/colbuilder/blob/main/docs/user_guide.md

Examples of crosslink configurations for different species.

```yaml
species: "homo_sapiens"
n_term_type: "HLKNL"
c_term_type: "HLKNL"
n_term_combination: "9.C - 947.A"
c_term_combination: "1047.C - 104.C"
```

```yaml
species: "bos_taurus"
n_term_type: "HLKNL"
c_term_type: "HLKNL"
n_term_combination: "9.C - 946.A"
c_term_combination: "1046.C - 103.C"
```

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

### PYD Crosslinks Configuration Example

Source: https://github.com/graeter-group/colbuilder/blob/main/README.md

Example configuration for creating a fibril with PYD (Pyridinoline) crosslinks, which are trivalent.

```yaml
# config_pyd_crosslinks.yaml
species: "homo_sapiens"
sequence_generator: true
geometry_generator: true
crosslink: true
n_term_type: "PYD"
c_term_type: "PYD"
n_term_combination: "6.B - 9.C - 946.A"
c_term_combination: "1046.C - 1046.A - 103.C"
fibril_length: 50.0
contact_distance: 20
```

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

### Install MUSCLE using Conda

Source: https://github.com/graeter-group/colbuilder/blob/main/README.md

Installs the MUSCLE tool for multiple sequence alignment using the Bioconda channel.

```bash
conda install bioconda::muscle
```

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

### General Configuration Options

Source: https://github.com/graeter-group/colbuilder/blob/main/docs/user_guide.md

Basic settings for logging and file paths.

```yaml
debug: false                # Enable detailed debug logging
working_directory: "./"     # Working directory for input and output files
```

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

### Install PyMOL netcdf dependency

Source: https://github.com/graeter-group/colbuilder/blob/main/README.md

Install specific netcdf version if PyMOL encounters library errors.

```bash
conda install -c conda-forge libnetcdf==4.7.3
```

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

### Define Configuration File

Source: https://github.com/graeter-group/colbuilder/blob/main/docs/user_guide.md

Create a YAML configuration file to specify species and structural parameters.

```yaml
# Basic human collagen microfibril configuration
species: "homo_sapiens"
sequence_generator: true
geometry_generator: true
crosslink: true
fibril_length: 60.0
contact_distance: 20
n_term_type: "HLKNL"
c_term_type: "HLKNL"
n_term_combination: "9.C - 947.A"
c_term_combination: "1047.C - 104.C"
```

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

### Create and Activate Virtual Environment

Source: https://github.com/graeter-group/colbuilder/blob/main/docs/user_guide.md

Initialize a dedicated Python 3.9 environment for ColBuilder.

```bash
conda create -n colbuilder python=3.9
conda activate colbuilder
```

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

### Run ColBuilder

Source: https://github.com/graeter-group/colbuilder/blob/main/docs/user_guide.md

Execute the pipeline using the provided configuration file.

```bash
colbuilder --config_file config.yaml
```

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

### Run ColBuilder with Configuration File

Source: https://github.com/graeter-group/colbuilder/blob/main/README.md

Execute the ColBuilder tool using a specified configuration file.

```bash
colbuilder --config_file config_human_basic.yaml
```

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

### Trivalent Crosslink Combinations

Source: https://github.com/graeter-group/colbuilder/blob/main/README.md

YAML configuration for specifying N-terminal and C-terminal trivalent crosslink combinations, using PYD as an example.

```yaml
# PYD crosslink example
n_term_combination: "6.B - 9.C - 946.A"
c_term_combination: "1046.C - 1046.A - 103.C"
```

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

### Configure Modeller Environment Variables

Source: https://github.com/graeter-group/colbuilder/blob/main/README.md

Sets environment variables for Modeller 10.5 to include its libraries in the Python path and library path. Adjust the base path to match your installation directory.

```bash
export PYTHONPATH="/home/user/bin/modeller10.5/lib/x86_64-intel8/python3.3:$PYTHONPATH"
export PYTHONPATH="/home/user/bin/modeller10.5/modlib:$PYTHONPATH"
export LD_LIBRARY_PATH="/home/user/bin/modeller10.5/lib/x86_64-intel8:$LD_LIBRARY_PATH"
```

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

### Run Full Pipeline

Source: https://github.com/graeter-group/colbuilder/blob/main/docs/user_guide.md

Executes the complete sequence-to-topology generation workflow.

```yaml
# config_full.yaml
species: "homo_sapiens"
sequence_generator: true
geometry_generator: true
topology_generator: true
crosslink: true
n_term_type: "HLKNL"
c_term_type: "HLKNL"
n_term_combination: "9.C - 947.A"
c_term_combination: "1047.C - 104.C"
fibril_length: 60.0
contact_distance: 20
force_field: "amber99"
```

```bash
colbuilder --config_file config_full.yaml
```

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

### Clone the Repository

Source: https://github.com/graeter-group/colbuilder/blob/main/CONTRIBUTING.md

Initializes a local copy of the project by cloning the fork.

```bash
git clone git@github.com:YOUR-USERNAME/colbuilder.git
cd colbuilder
```

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

### Basic ColBuilder Usage

Source: https://github.com/graeter-group/colbuilder/blob/main/README.md

The general command-line syntax for running ColBuilder with a configuration file and optional arguments.

```bash
colbuilder --config_file config.yaml [OPTIONS]
```

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

### Run ColBuilder with Configuration File

Source: https://github.com/graeter-group/colbuilder/blob/main/README.md

Command to execute ColBuilder using a specified configuration file.

```bash
colbuilder --config_file config_pyd_fibril.yaml
```

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

### Generate Topology Files

Source: https://github.com/graeter-group/colbuilder/blob/main/docs/examples/colbuilder.md

Generate topology and coordinate files for molecular dynamics simulations using ColBuilder. Requires a configuration file specifying the force field.

```bash
colbuilder --config_file config.yaml --topology_generator
```

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

### Execute ColBuilder via CLI

Source: https://context7.com/graeter-group/colbuilder/llms.txt

Basic command line operations for running simulations, debugging, and accessing help.

```bash
# Basic usage with configuration file
colbuilder --config_file config.yaml

# Enable debug mode to keep intermediate files
colbuilder --config_file config.yaml --debug

# Verify installation
colbuilder --help

# Show version
colbuilder --version
```

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

### Topology Configuration

Source: https://github.com/graeter-group/colbuilder/blob/main/docs/user_guide.md

Settings for force field selection.

```yaml
topology_generator: false   # Enable topology generation
force_field: "amber99"      # Force field to use (amber99 or martini3)
```

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

### Run Colbuilder Workflow Steps

Source: https://github.com/graeter-group/colbuilder/blob/main/docs/examples/example5/example5.2/Readme.md

Execute the three-step Colbuilder process to generate, mutate, and refine collagen fibril geometry.

```bash
# 1) Enzymatic crosslinks on a fresh sequence
colbuilder --config_file config_ex5_step1_enzymatic.yaml --debug

# 2) Add non-enzymatic crosslink(s) on the pre-mutated PDB
colbuilder --config_file config_ex5_step2_nonenzymatic.yaml --debug

# 3) Build geometry, replace selected crosslinks, and generate topology
colbuilder --config_file config_ex5_step3.yaml --debug
```

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

### Step 2: Add AGE Crosslinks to Existing Structure

Source: https://github.com/graeter-group/colbuilder/blob/main/README.md

Configuration for the second step in adding AGE crosslinks. It takes the output from Step 1, adds additional crosslinks (e.g., Glucosepane), and customizes crosslink optimization.

```yaml
# config_add_age_step2.yaml
species: "rattus_norvegicus"
sequence_generator: true
geometry_generator: false
topology_generator: false

mutated_pdb: "rattusnorvegicus_N_PYD_C_PYD.pdb"

crosslink: true
# Terminal crosslinks must match step 1
n_term_type: "PYD"
c_term_type: "PYD"
n_term_combination: "6.B - 9.C - 946.A"
c_term_combination: "1046.C - 1046.A - 103.C"

# Add Glucosepane AGE crosslink
additional_1_type: "Glucosepane"
additional_1_combination: "1055.C - 822.A"

# Customize crosslink optimization
crosslink_copies: ["D2", "D3"]
```

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

### Basic ColBuilder YAML Configuration

Source: https://github.com/graeter-group/colbuilder/blob/main/docs/configuration.md

A template demonstrating the structure and default values for a ColBuilder configuration file.

```yaml
# Basic configuration
mode: null
config_file: null
sequence_generator: true
geometry_generator: true
topology_generator: false
debug: false
working_directory: "./"

# Input Configuration
species: "homo_sapiens"
mutated_pdb: null
fasta_file: null

# Sequence Settings
crosslink: true
n_term_type: "HLKNL"
c_term_type: "HLKNL"
n_term_combination: "9.C - 947.A"
c_term_combination: "1047.C - 104.C"

# Geometry Parameters
pdb_file: null
contact_distance: 20
fibril_length: 60.0
crystalcontacts_file: null
connect_file: null
crystalcontacts_optimize: false

# Mixing Options
mix_bool: false
ratio_mix: "D:70 T:30"
files_mix:
 - "human-D.pdb"
 - "human-T.pdb"

# Replacement Options
replace_bool: false
ratio_replace: 30
replace_file: null

# Topology Options
force_field: "amber99"
topology_debug: false
```

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

### Run ColBuilder Workflow Stages

Source: https://github.com/graeter-group/colbuilder/blob/main/docs/examples/example5/example5.1/Readme.md

Execute the three sequential stages of the ColBuilder workflow using specific configuration files.

```bash
# 1) Enzymatic crosslinks on a fresh sequence
colbuilder --config_file config_ex5_step1_enzymatic.yaml --debug

# 2) Add non-enzymatic crosslink(s) on the pre-mutated PDB
colbuilder --config_file config_ex5_step2_nonenzymatic.yaml --debug

# 3) Build geometry and topology using the final PDB
colbuilder --config_file config_ex5_step3.yaml --debug
```

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

### Clone Repository

Source: https://github.com/graeter-group/colbuilder/blob/main/docs/user_guide.md

Download the ColBuilder source code from GitHub.

```bash
git clone git@github.com:graeter-group/colbuilder.git
cd colbuilder
```

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

### Enable Debug Mode

Source: https://github.com/graeter-group/colbuilder/blob/main/docs/examples/example4/Readme.md

Add these parameters to the configuration file to preserve intermediate files and logs for troubleshooting.

```yaml
debug: true
topology_debug: true
```

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

### Configure Full Pipeline

Source: https://context7.com/graeter-group/colbuilder/llms.txt

YAML configuration for generating a complete collagen microfibril and the corresponding execution command.

```yaml
# config_full_pipeline.yaml
# Complete pipeline: sequence -> geometry -> topology

# Operation modes
sequence_generator: true    # Generate triple helix from sequence
geometry_generator: true    # Build microfibril from triple helix
topology_generator: true    # Generate GROMACS topology files
debug: false
working_directory: "./"

# Species selection (19+ available)
species: "homo_sapiens"

# Crosslink configuration (divalent HLKNL)
crosslink: true
n_term_type: "HLKNL"
c_term_type: "HLKNL"
n_term_combination: "9.C - 947.A"
c_term_combination: "1047.C - 104.C"

# Geometry parameters
contact_distance: 20        # Radial size control (Angstroms)
fibril_length: 60.0         # Fibril length (nanometers)

# Topology settings
force_field: "amber99"      # Options: "amber99", "martini3"
```

```bash
# Run the full pipeline
colbuilder --config_file config_full_pipeline.yaml

# Expected output files:
# - homosapiens_alignment.fasta (sequence alignment)
# - homosapiens_N_HLKNL_C_HLKNL.pdb (triple helix)
# - collagen_fibril_homo_sapiens.pdb (microfibril)
# - homo_sapiens_topology_files/ (GROMACS topology)
```

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

### Create Branch and Commit Changes

Source: https://github.com/graeter-group/colbuilder/blob/main/CONTRIBUTING.md

Standard workflow for creating a feature branch and pushing changes to the remote repository.

```bash
git checkout -b feature/your-feature-name
# Make your changes
git commit -m "Add feature: description"
git push origin feature/your-feature-name
```

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

### Custom Sequence Configuration

Source: https://github.com/graeter-group/colbuilder/blob/main/docs/user_guide.md

Configuration for using a custom FASTA file.

```yaml
species: "custom_species"
fasta_file: "path/to/custom_sequence.fasta"
sequence_generator: true
crosslink: false
```

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

### Run Colbuilder Mixed-Crosslink Workflow

Source: https://github.com/graeter-group/colbuilder/blob/main/docs/examples/example5/example5.3/HLKNL+PYD+MOLD+Glucosepane+Pentosideine/Readme.md

Execute the sequence generation, mutation, and mixing steps using the colbuilder CLI.

```bash
# 1) Enzymatic-position sequences (HLKNL, PYD, MOLD)
colbuilder --config_file config_ex5_step1_HLKNL.yaml --debug
colbuilder --config_file config_ex5_step3_PYD.yaml --debug
colbuilder --config_file config_ex5_step5_MOLD.yaml --debug

# 2) Add non-enzymatic crosslinks
colbuilder --config_file config_ex5_step2_HLKNL+Glucosepane.yaml --debug
colbuilder --config_file config_ex5_step4_PYD+Pentosidine.yaml --debug
colbuilder --config_file config_ex5_step6_MOLD+Pentosidine.yaml --debug

# 3) Mix the three inputs and generate topology
colbuilder --config_file config_ex5_step7.yaml --debug
```

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

### Execute Three-Step AGE Crosslink Workflow

Source: https://context7.com/graeter-group/colbuilder/llms.txt

Execute the three-step workflow for adding AGE crosslinks by running Collabuilder with each configuration file sequentially. Debug flags can be enabled for detailed output.

```bash
# Execute three-step workflow
colbuilder --config_file config_step1_enzymatic.yaml --debug
colbuilder --config_file config_step2_nonenzymatic.yaml --debug
colbuilder --config_file config_step3_geometry.yaml --debug

# Outputs:
# - rattusnorvegicus_N_PYD_C_PYD.pdb (enzymatic crosslinks)
# - rattusnorvegicus_N_PYD_C_PYD+ADD1_Glucosepane.pdb (with AGE)
# - collagen_fibril_rattus_norvegicus.pdb (final fibril)
# - rattus_norvegicus_topology_files/ (GROMACS topology)
```

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

### Run ColBuilder Topology-Only Mode

Source: https://github.com/graeter-group/colbuilder/blob/main/docs/examples/example4/Readme.md

Execute the ColBuilder tool using a specified configuration file.

```bash
colbuilder --config_file config_ex4.yaml
```

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

### Run Colbuilder with Configuration

Source: https://github.com/graeter-group/colbuilder/blob/main/docs/examples/example3/Readme.md

Execute the colbuilder tool with a specified configuration file to modify fibril properties. Ensure the config_replace.yaml file is correctly formatted.

```bash
colbuilder -f config_file config_replace.yaml
```

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

### Run ColBuilder for Mixed Crosslinks

Source: https://github.com/graeter-group/colbuilder/blob/main/README.md

Execute ColBuilder sequentially for generating individual crosslink types and then mixing them.

```bash
colbuilder --config_file config_divalent_molecule.yaml
colbuilder --config_file config_trivalent_molecule.yaml
colbuilder --config_file config_mixed_crosslinks.yaml
```

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

### Run ColBuilder in Three Steps for AGE Crosslinks

Source: https://github.com/graeter-group/colbuilder/blob/main/README.md

Sequence of commands to execute the three-step workflow for adding AGE crosslinks to a collagen structure.

```bash
# Run in three steps
colbuilder --config_file config_add_age_step1.yaml
colbuilder --config_file config_add_age_step2.yaml
colbuilder --config_file config_add_age_step3.yaml
```

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

### ColBuilder Configuration Parameters

Source: https://github.com/graeter-group/colbuilder/blob/main/docs/data_dictionary.md

Reference for the configuration parameters used to initialize and run the ColBuilder workflow.

```APIDOC
## Configuration Parameters

### Description
Parameters used to configure the ColBuilder workflow, including species selection, generator toggles, and crosslink definitions.

### Parameters
#### Request Body
- **species** (string) - Required - Species name for collagen sequence (e.g., "homo_sapiens")
- **sequence_generator** (boolean) - Optional - Enable sequence generation
- **geometry_generator** (boolean) - Optional - Enable geometry generation
- **topology_generator** (boolean) - Optional - Enable topology generation
- **mutated_pdb** (string) - Optional - Pre-mutated PDB for additional crosslinks
- **crosslink** (boolean) - Optional - Enable crosslinking
- **n_term_type** (string) - Optional - N-terminal crosslink type (e.g., "HLKNL")
- **c_term_type** (string) - Optional - C-terminal crosslink type (e.g., "HLKNL")
- **n_term_combination** (string) - Optional - N-terminal residue combination (e.g., "9.C - 947.A")
- **c_term_combination** (string) - Optional - C-terminal residue combination (e.g., "1047.C - 104.C")
- **additional_1_type** (string) - Optional - First additional crosslink type (e.g., "Glucosepane")
- **additional_1_combination** (string) - Optional - Position for first additional crosslink (e.g., "1008.A - 767.B")
- **crosslink_copies** (array) - Optional - Periodic copies for optimization (e.g., ["D0", "D5"])
- **fibril_length** (float) - Optional - Length of microfibril (nm)
- **contact_distance** (float) - Optional - Contact distance (Å)
- **force_field** (string) - Optional - Force field for topology (e.g., "amber99")
- **debug** (boolean) - Optional - Keep intermediate files for debugging
- **working_directory** (string) - Optional - Working directory for input/output files
```

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

### Step 1: Base Structure with Enzymatic Crosslinks

Source: https://context7.com/graeter-group/colbuilder/llms.txt

Configure the base structure with enzymatic crosslinks. This YAML file defines species, crosslinking parameters, and terminal types for the initial step.

```yaml
# Step 1: config_step1_enzymatic.yaml - Base structure
species: "rattus_norvegicus"
sequence_generator: true
geometry_generator: false
crosslink: true
n_term_type: "PYD"
c_term_type: "PYD"
n_term_combination: "9.C - 5.B - 944.B"
c_term_combination: "1046.C - 1046.A - 103.C"
```

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

### Run Colbuilder Workflow for Mixed Crosslinks

Source: https://github.com/graeter-group/colbuilder/blob/main/docs/examples/example5/example5.3/HLKNL+PYD+Glucosepane+Pentosidine/Readme.md

Executes the sequence generation, non-enzymatic crosslink addition, and final mixing steps in order.

```bash
# 1) Enzymatic-only sequences
colbuilder --config_file config_ex5_step1_HLKNL_seq.yaml --debug
colbuilder --config_file config_ex5_step3_PYD_seq.yaml --debug

# 2) Add non-enzymatic crosslinks
colbuilder --config_file config_ex5_step2_HLKNL+Glucosepane.yaml --debug
colbuilder --config_file config_ex5_step4_PYD+Pentosidine.yaml --debug

# 3) Mix the two variants and generate topology
colbuilder --config_file config_ex5_step5.yaml --debug
```

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

### Execute Topology-Only Mode

Source: https://context7.com/graeter-group/colbuilder/llms.txt

Run Collabuilder with the topology-only configuration to generate GROMACS topology files from a pre-existing PDB structure.

```bash
colbuilder --config_file config_topology_only.yaml

# Output: homo_sapiens_topology_files/
#   - collagen_fibril_homo_sapiens.top
#   - collagen_fibril_homo_sapiens.gro
#   - col_*.itp (per-chain topology)
#   - posre_*.itp (position restraints)
#   - amber99sb-star-ildnp.ff/ (force field)
```

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

### Step 1: Generate Base Structure with Enzymatic Crosslinks

Source: https://github.com/graeter-group/colbuilder/blob/main/README.md

Configuration for the first step in adding AGE crosslinks, focusing on generating a base structure with enzymatic crosslinks.

```yaml
# config_add_age_step1.yaml
species: "rattus_norvegicus"
sequence_generator: true
geometry_generator: false
topology_generator: false
crosslink: true

# Base terminal crosslinks
n_term_type: "PYD"
c_term_type: "PYD"
n_term_combination: "6.B - 9.C - 946.A"
c_term_combination: "1046.C - 1046.A - 103.C"
```

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

### Execute Coarse-Grained Topology Generation

Source: https://context7.com/graeter-group/colbuilder/llms.txt

Run Collabuilder with the Martini3 configuration to generate coarse-grained topology files for a collagen molecule.

```bash
colbuilder --config_file config_martini.yaml
```

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

### Configure AGE Crosslink Workflow

Source: https://github.com/graeter-group/colbuilder/blob/main/docs/configuration.md

A three-step workflow for generating a base structure, adding AGE crosslinks, and building the final fibril.

```yaml
# config_step1.yaml
species: "rattus_norvegicus"
sequence_generator: true
geometry_generator: false
crosslink: true
n_term_type: "PYD"
c_term_type: "PYD"
n_term_combination: "6.B - 9.C - 946.A"
c_term_combination: "1046.C - 1046.A - 103.C"
```

```yaml
# config_step2.yaml
species: "rattus_norvegicus"
sequence_generator: true
geometry_generator: false
mutated_pdb: "rattusnorvegicus_N_PYD_C_PYD.pdb"
crosslink: true
n_term_type: "PYD"
c_term_type: "PYD"
n_term_combination: "6.B - 9.C - 946.A"
c_term_combination: "1046.C - 1046.A - 103.C"
additional_1_type: "Glucosepane"
additional_1_combination: "1055.C - 822.A"
crosslink_copies: ["D2", "D3"]
```

```yaml
# config_step3.yaml
species: "rattus_norvegicus"
sequence_generator: false
geometry_generator: true
topology_generator: true
pdb_file: "rattusnorvegicus_N_PYD_C_PYD+ADD1_Glucosepane.pdb"
crosslink: true
n_term_type: "PYD"
c_term_type: "PYD"
n_term_combination: "6.B - 9.C - 946.A"
c_term_combination: "1046.C - 1046.A - 103.C"
fibril_length: 40.0
contact_distance: 20
force_field: "amber99"
```

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

### Basic ColBuilder Configuration File

Source: https://github.com/graeter-group/colbuilder/blob/main/README.md

A sample YAML configuration file for generating a basic human collagen microfibril. It specifies species, enables sequence and geometry generation, and defines crosslinking parameters.

```yaml
# Basic human collagen microfibril configuration   
species: "homo_sapiens"
sequence_generator: true
geometry_generator: true
crosslink: true
fibril_length: 60.0
contact_distance: 20
n_term_type: "HLKNL"
c_term_type: "HLKNL"
n_term_combination: "9.C - 947.A"
c_term_combination: "1047.C - 104.C"
```

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

### ColBuilder Configuration File Template

Source: https://github.com/graeter-group/colbuilder/blob/main/README.md

A comprehensive YAML template for ColBuilder configuration, detailing options for sequence generation, geometry generation, topology generation, and general settings.

```yaml
# ================================================================================
# ColBuilder Configuration File
# ================================================================================
# The pipeline consists of three main modules that can be run 
# independently or in combination:
#
# 1. SEQUENCE GENERATOR: Creates collagen triple helix structures from sequences
# 2. GEOMETRY GENERATOR: Builds collagen microfibrils from triple helices
# 3. TOPOLOGY GENERATOR: Generates force field topologies for simulations
#
# IMPORTANT: When using additional crosslinks with a pre-mutated PDB, 
# e.g. to add AGE crosslinks:
# - Run sequence generation first to apply and optimize additional crosslinks
# - Then run geometry generation in a separate execution using the output PDB
# ================================================================================

# Operation Mode
mode: null
config_file: null            # Path to another config file (for nested configs)  
sequence_generator: true     # Generate triple helix structure from sequence
geometry_generator: true     # Build microfibril from triple helix
topology_generator: false    # Generate simulation topology files
debug: false                 # Keep intermediate files for debugging
working_directory: "./"      # Directory for output files

```

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

### Configure Force Field Parameters

Source: https://github.com/graeter-group/colbuilder/blob/main/docs/examples/example4/Readme.md

Specify the force field representation in the configuration file.

```yaml
force_field: "amber99"
```

```yaml
force_field: "martini3"
```

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

### Step 2: Add AGE Crosslinks

Source: https://context7.com/graeter-group/colbuilder/llms.txt

Add non-enzymatic Advanced Glycation End-products (AGE) crosslinks. This configuration references the output PDB from Step 1 and specifies additional crosslinks like Glucosepane.

```yaml
# Step 2: config_step2_nonenzymatic.yaml - Add Glucosepane AGE
species: "rattus_norvegicus"
sequence_generator: true
geometry_generator: false
crosslink: true

# Reference the output from step 1
mutated_pdb: "rattusnorvegicus_N_PYD_C_PYD.pdb"

# Terminal crosslinks must match step 1
n_term_type: "PYD"
c_term_type: "PYD"
n_term_combination: "9.C - 5.B - 944.B"
c_term_combination: "1046.C - 1046.A - 103.C"

# Additional AGE crosslink
additional_1_type: "Glucosepane"
additional_1_combination: "523.A - 286.C"

# Crosslink optimization settings
crosslink_copies: ["D2", "D1"]
```

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

### POST /configuration/input

Source: https://github.com/graeter-group/colbuilder/blob/main/docs/configuration.md

Configures the input parameters for collagen sequence and structure generation, including species selection and file paths for custom sequences or PDB templates.

```APIDOC
## POST /configuration/input

### Description
Sets the input configuration for the ColBuilder tool. This endpoint defines the species for sequence retrieval and allows for the injection of custom FASTA files or pre-mutated PDB structures.

### Method
POST

### Endpoint
/configuration/input

### Parameters
#### Request Body
- **species** (string) - Optional - Species for collagen sequence and structure. Defaults to "homo_sapiens".
- **mutated_pdb** (string) - Optional - Path to pre-mutated PDB for adding additional crosslinks.
- **fasta_file** (string) - Optional - Path to custom FASTA file. Overrides built-in species sequence.

### Request Example
{
  "species": "homo_sapiens",
  "mutated_pdb": "/path/to/structure.pdb",
  "fasta_file": null
}

### Response
#### Success Response (200)
- **status** (string) - Confirmation of configuration update.
```

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

### ColBuilder Output Files Reference

Source: https://context7.com/graeter-group/colbuilder/llms.txt

This section outlines the generated output files for sequence, geometry, and topology generation. The file names and directory structures depend on the specified species and force field.

```bash
# Sequence Generation Output:
{species}_alignment.fasta           # Multiple sequence alignment
{species}_N_{n_type}_C_{c_type}.pdb # Triple helix with crosslinks

# Geometry Generation Output:
collagen_fibril_{species}.pdb       # Complete microfibril structure

# Topology Generation Output (Amber99):
{species}_topology_files/
  collagen_fibril_{species}.top     # Main topology file
  collagen_fibril_{species}.gro     # GROMACS coordinate file
  col_*.itp                         # Per-chain topology includes
  posre_*.itp                       # Position restraints
  amber99sb-star-ildnp.ff/          # Force field directory
```

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

### Topology Generation Parameters

Source: https://github.com/graeter-group/colbuilder/blob/main/docs/configuration.md

Parameters controlling the generation of topology files for molecular dynamics simulations.

```APIDOC
## Topology Generation Parameters

### Description
These parameters control the generation of topology files for molecular dynamics simulations.

### Parameters
#### Request Body
- **force_field** (string) - Optional - Force field for topology generation, default: "amber99"
- **topology_debug** (boolean) - Optional - Save intermediate topology files for debugging, default: false

### Available Force Field Options
- **amber99**: Standard Amber99 force field for atomistic simulations
- **martini3**: Martini 3 coarse-grained force field

### Notes
- The `force_field` parameter selects which force field to use for generating topology files.
- The amber99 force field is recommended for most atomistic simulations of collagen.
- Custom force field parameters for collagen and crosslinks are included in ColBuilder.
- Set `topology_debug: true` to keep intermediate files for troubleshooting topology generation issues.
- **Topology-only mode**: When both `sequence_generator` and `geometry_generator` are false, topology generation can process existing fibril PDB files directly.
```

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

### Geometry Generation Configuration

Source: https://github.com/graeter-group/colbuilder/blob/main/docs/user_guide.md

Settings for fibril dimensions and PDB inputs.

```yaml
geometry_generator: true    # Enable geometry generation
pdb_file: null              # Input PDB file (if sequence_generator is false)
contact_distance: 20        # Distance threshold for contacts (Å)
fibril_length: 60.0         # Length of the generated fibril (nm)
crystalcontacts_file: null  # File with crystal contacts info
connect_file: null          # File with connections between contacts
crystalcontacts_optimize: false # Optimize crystal contacts
```

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

### Run ColBuilder for Crosslink Replacement

Source: https://github.com/graeter-group/colbuilder/blob/main/README.md

Command to execute ColBuilder for replacing crosslinks using a specified configuration file.

```bash
colbuilder --config_file config_replace_crosslinks.yaml
```

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

### Make UCSF Chimera Executable

Source: https://github.com/graeter-group/colbuilder/blob/main/README.md

Changes the permissions of the downloaded UCSF Chimera binary to make it executable. Ensure you are in the directory where the file was downloaded.

```bash
cd ~/Downloads  # or wherever you downloaded the file
chmod +x chimera*.bin
./chimera*.bin
```

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

### Select Force Fields

Source: https://github.com/graeter-group/colbuilder/blob/main/docs/user_guide.md

Specify the force field for molecular dynamics simulations.

```yaml
topology_generator: true
force_field: "amber99"      # For all-atom simulations
```

```yaml
topology_generator: true
force_field: "martini3"     # For coarse-grained simulations
```

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

### Execute Crosslink Replacement

Source: https://context7.com/graeter-group/colbuilder/llms.txt

Run Collabuilder with the specified configuration file to modify the PDB and reduce crosslink density.

```bash
colbuilder --config_file config_replace.yaml

# Output: Modified fibril with reduced crosslinking
```

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

### Replacement Configuration

Source: https://github.com/graeter-group/colbuilder/blob/main/docs/user_guide.md

Settings for replacing crosslinks with lysines.

```yaml
replace_bool: false         # Enable replacement of crosslinks with lysines
ratio_replace: 30           # Percentage of crosslinks to replace
replace_file: null          # File with crosslinks to be replaced
```

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

### Generate Collagen Sequence and Homology Model

Source: https://github.com/graeter-group/colbuilder/blob/main/docs/examples/colbuilder.md

Use ColBuilder to generate a collagen sequence and perform homology modeling. Requires a configuration file.

```bash
colbuilder --config_file config.yaml --sequence_generator
```

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

### Mixing Configuration

Source: https://github.com/graeter-group/colbuilder/blob/main/docs/user_guide.md

Settings for mixing different crosslink types.

```yaml
mix_bool: false             # Enable mixing of different crosslink types
ratio_mix: "D:70 T:30"      # Ratio for different crosslink types
files_mix:                  # Required if mix_bool is true
 - "human-D.pdb"            # PDB file with type D crosslinks
 - "human-T.pdb"            # PDB file with type T crosslinks
```

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

### Step 3: Build Fibril Geometry

Source: https://context7.com/graeter-group/colbuilder/llms.txt

Generate the final fibril structure. This configuration specifies the input PDB (with AGE crosslinks), crosslink details, and simulation parameters like contact distance and fibril length.

```yaml
# Step 3: config_step3_geometry.yaml - Build fibril
species: "rattus_norvegicus"
sequence_generator: false
geometry_generator: true
topology_generator: true

pdb_file: "rattusnorvegicus_N_PYD_C_PYD+ADD1_Glucosepane.pdb"

crosslink: true
n_term_type: "PYD"
c_term_type: "PYD"
n_term_combination: "9.C - 5.B - 944.B"
c_term_combination: "1046.C - 1046.A - 103.C"

contact_distance: 25
fibril_length: 67.0
force_field: "amber99"
```