coot-best-practices

name	coot-best-practices
description	Best Practices for using Coot MCP

Coot Python API Best Practices

Overview

This skill provides best practices for interacting with Coot's Python API through the MCP server. Following these guidelines ensures optimal performance, correct usage, and reliable results.

Python Execution in Coot MCP

CRITICAL: Understanding run_python() vs run_python_multiline()

Coot MCP provides two tools for executing Python code with different capabilities and limitations:

run_python() - Simple Expressions Only

Use for single expressions that return a value. Cannot handle imports or semicolons.

# ✓ CORRECT - single expression, no imports
coot.run_python("1 + 1")                           # Returns: 2
coot.run_python("coot.molecule_name(0)")           # Returns: molecule name
coot.run_python("coot.is_valid_model_molecule(0)") # Returns: 1 or 0

# ✗ WRONG - these will all fail with syntax errors
coot.run_python("import os")                       # FAILS - import not allowed
coot.run_python("import os; os.getcwd()")          # FAILS - semicolon not allowed  
coot.run_python("x = 5; x * 2")                    # FAILS - semicolon not allowed
coot.run_python("import coot_utils; coot_utils.chain_ids(0)")  # FAILS

Rule: Use run_python() ONLY for:

• Single expressions with no semicolons
• No import statements
• Direct function calls that return a value

run_python_multiline() - Everything Else

Use for any code requiring imports, multiple statements, or function definitions:

# ✓ CORRECT - use multiline for imports
coot.run_python_multiline("""
import os
result = os.getcwd()
print(result)
""")

# ✓ CORRECT - use multiline for multiple statements
coot.run_python_multiline("""
x = 5
y = x * 2
print(y)
""")

# ✓ CORRECT - use multiline for complex logic
coot.run_python_multiline("""
import coot_utils
chains = coot_utils.chain_ids(0)
for chain in chains:
    print(f"Chain: {chain}")
""")

# ✓ CORRECT - use multiline for function definitions
coot.run_python_multiline("""
def validate_residue(imol, chain, resno):
    info = coot.residue_info_py(imol, chain, resno, "")
    return len(info)

result = validate_residue(0, "A", 42)
print(f"Atoms: {result}")
""")

Rule: Use run_python_multiline() for:

• Any import statements
• Multiple statements (even without imports)
• Function definitions
• Loops and control flow
• Anything with complexity

Key Differences Table

Feature	run_python()	run_python_multiline()
Import statements	❌ Fails	✓ Works
Semicolons	❌ Fails	✓ Works
Multiple lines	❌ Fails	✓ Works
Function defs	❌ Fails	✓ Works
Simple expressions	✓ Works	✓ Works
Return value	Returns value	Returns None (use print)

Common Mistake Pattern

# ❌ WRONG - will fail with "invalid syntax"
result = coot.run_python("import coot_utils; coot_utils.chain_ids(0)")

# ✓ CORRECT - use multiline
coot.run_python_multiline("""
import coot_utils
chains = coot_utils.chain_ids(0)
print(chains)
""")

When in Doubt

Use run_python_multiline() - it handles everything run_python() can do, plus more. The only downside is that it returns None rather than a value, so use print() to see output.

File Writing from Coot Python

CRITICAL: When writing files from Coot's Python, ALWAYS write to the current directory without specifying a path.

The Problem

Coot's Python interpreter runs in a specific working directory (/Users/pemsley/Projects/coot/git/coot-main/build/src), which is different from both:

• The bash working directory (/home/claude)
• Mounted shared directories (/mnt/user-data/...)

Attempting to write to an explicit path that doesn't exist in Coot's context will cause FileNotFoundError.

✅ CORRECT: Write to Current Directory

# ✓ CORRECT - no path, just filename
with open('output.txt', 'w') as f:
    f.write(content)

# ✓ CORRECT - works for any file type
with open('validation.xml', 'w') as f:
    f.write(xml_content)

# ✓ CORRECT - reading also uses just filename
with open('data.txt', 'r') as f:
    content = f.read()

❌ INCORRECT: Don't Specify Paths

# ✗ WRONG - will fail with FileNotFoundError
with open('/home/claude/output.txt', 'w') as f:
    f.write(content)

# ✗ WRONG - this path doesn't exist in Coot's context
with open('/mnt/user-data/outputs/file.txt', 'w') as f:
    f.write(content)

# ✗ WRONG - even full paths will fail
import os
output_file = os.path.join('/home/claude', 'output.txt')
with open(output_file, 'w') as f:
    f.write(content)

Pattern for Working with Files

# 1. Download/fetch content (if needed)
url = "https://example.com/data.xml"
content = coot.coot_get_url_as_string_py(url)

# 2. Write to current directory (no path!)
with open('data.xml', 'w') as f:
    f.write(content)

# 3. Process the file
import xml.etree.ElementTree as ET
tree = ET.parse('data.xml')  # Read from current directory
root = tree.getroot()

# 4. Write results (again, no path!)
with open('results.txt', 'w') as f:
    f.write(analysis_results)

Why This Works

Coot's Python interpreter automatically uses its working directory. By omitting paths:

• Files are created in a location that exists
• No permission issues
• No cross-filesystem problems
• Simple and reliable

User Talk

When the user says "here" in an ambiguous way, they typically mean "applying the relevant function to this residue (or atom or chain)" - i.e. the residue (or atom or chain) at the centre of the screen.

Getting Files to the User [warning: this needs review!]

After creating files in Coot's working directory, use bash tools to copy them to /mnt/user-data/outputs where the user can access them, or share results via print output.

Startup Procedure

CRITICAL: On every "Coot Mode" start, before doing anything else:

1. Read the /mnt/skills/user/coot-essential-api/SKILL.md file
2. Extract all function names mentioned in that file
3. Call get_function_descriptions() with the complete list of function names
4. This loads the essential API documentation into context, providing immediate access to the ~25 core functions needed for typical validation and model-building workflows

Why get_function_descriptions and not search_coot_functions? search_coot_functions can return sparse or incomplete docs for some functions. get_function_descriptions retrieves the full docstring including return value structure. Always prefer get_function_descriptions for known function names — use search_coot_functions only when you don't know the function name yet.

Example:

# After reading coot-essential-api/SKILL.md, call:
Coot:get_function_descriptions([
    "set_refinement_immediate_replacement",
    "set_imol_refinement_map",
    "is_valid_model_molecule",
    "is_valid_map_molecule",
    "get_hydrogen_bonds_py",
    # ... all other functions from the essential API
])

Only after completing this startup should you proceed with the user's task.

Critical Rule: Prefer C++ Functions Over Python Wrappers

ALWAYS use coot.*_py() functions directly instead of coot_utils.* equivalents when they are simple passthroughs.

Why?

1. Performance: C++ functions are significantly faster (no Python overhead)
2. Import requirements: coot is auto-imported, coot_utils requires explicit import
3. Simplicity: Direct access to the core API without unnecessary abstraction layers
4. Reliability: Fewer layers means fewer potential points of failure

Module Import Requirements

Auto-imported

• coot - The core C++/SWIG binding is automatically available
• No import statement needed

Requires explicit import

• coot_utils - Python utility library built on top of coot
• Must execute: import coot_utils before using any of its functions

Example of the problem:

# This will fail with NameError if coot_utils not imported
coot_utils.chain_ids(0)

# Solution:
import coot_utils
coot_utils.chain_ids(0)  # Now works

But in this case (for chain-ids), this is preferred:

coot.get_chain_ids_py(0)

Function Naming Conventions

C++ Functions (SWIG bindings)

• End with _py() suffix
• Examples: closest_atom_simple_py(), is_valid_model_molecule(), chain_id_py()
• These are the core functions - prefer these

Python Wrapper Functions

• No _py() suffix
• Examples: closest_atom(), closest_atom_simple(), chain_ids()
• Only use when they provide genuine convenience

Specific Function Guidance

✅ CORRECT: Getting Closest Atom

# Get closest atom across all displayed molecules
atom_spec = coot.closest_atom_simple_py()
# Returns: [imol, chain-id, resno, ins-code, atom-name, alt-conf, [x, y, z]]

# Get closest atom in specific molecule
atom_spec = coot.closest_atom_py(0)
# Returns: [imol, chain-id, resno, ins-code, atom-name, alt-conf, [x, y, z]]

# Get raw closest atom (no CA substitution)
atom_spec = coot.closest_atom_raw_py()

❌ INCORRECT: Don't use coot_utils for simple passthroughs

# DON'T DO THIS - unnecessary import and no added value
import coot_utils
atom_spec = coot_utils.closest_atom(0)  # Just calls coot.closest_atom_py()

# DON'T DO THIS EITHER
atom_spec = coot_utils.closest_atom_simple()  # Just calls coot.closest_atom_simple_py()

✅ CORRECT: When to use coot_utils

Use coot_utils functions when they provide genuine convenience or abstraction:

import coot_utils

# chain_ids() is a convenience wrapper that constructs a list
# It calls coot.chain_id_py() in a loop and builds a list
chains = coot_utils.chain_ids(0)  # Returns: ['A', 'B']

# Without coot_utils, you'd have to do:
n = coot.n_chains(0)
chains = [coot.chain_id_py(0, i) for i in range(n)]

Checking Molecule Validity

# ✅ CORRECT: Direct C++ function
if coot.is_valid_model_molecule(0):
    print("Molecule 0 is a valid model")

if coot.is_valid_map_molecule(1):
    print("Molecule 1 is a valid map")

# ❌ INCORRECT: Don't use coot_utils for this
import coot_utils
if coot_utils.valid_model_molecule_qm(0):  # Unnecessary
    pass

Getting Molecule Information

# ✅ CORRECT: Direct access
name = coot.molecule_name(0)
n_chains = coot.n_chains(0)

# ✅ CORRECT: When coot_utils adds value
import coot_utils
chains = coot_utils.chain_ids(0)  # Convenience wrapper

MMDB Atom Selection Syntax

When using functions like new_molecule_by_atom_selection(), superpose_with_atom_selection(), or get_hydrogen_bonds_py(), use MMDB CID (Coordinate ID) strings to specify which atoms to include.

Format

/mdl/chn/s1.i1-s2.i2/atm[elm]:aloc

or for residue-name-based selection:

/mdl/chn/*(res)/atm[elm]:aloc

Components

• mdl - Model number (0 or * for any model; /1/ for model 1; // is shorthand for any model)
• chn - Chain ID (e.g., A, B, X)
  • Comma-separated list: A,B,C
  • Negation with !: !A,B selects all chains except A and B
  • * for all chains (default)
• s1-s2 - Residue sequence number range:
  • Single: 50
  • Range: 10-20
  • With insertion codes: 33.A-120.B (residue 33 ins A through residue 120 ins B)
  • * for all residues (default)
• (res) - Residue name filter in parentheses
  • Single: (HIS)
  • Comma-separated list: (ALA,SER,GLY)
  • Negation: (!ALA,SER) selects everything except ALA and SER
• .ic - Insertion code (e.g., .A)
• atm - Atom name (e.g., CA, N, O)
  • Comma-separated list: CA,N,O
  • Negation: !CA,CB selects all atoms except CA and CB
• [elm] - Element in square brackets (e.g., [C], [N], [FE])
  • Useful for disambiguation: CA[C] selects C-alpha (carbon), not calcium
  • Comma-separated list: [C,N,O]
  • Negation: [!H] selects all non-hydrogen atoms
• :aloc - Alternate location indicator
  • :A selects alt-loc A
  • :,A selects atoms with no alt-loc or alt-loc A
  • Defaults to "" (no alt-loc) when atom or element is specified

All components are optional and default to * (match everything) when omitted.

Negation

Any of the comma-separated list fields (chain, residue name, atom name, element, alt-loc) can be negated by prefixing with !:

"//!A"                         # All chains except A
"//A/(!GLY,ALA)"               # Non-GLY, non-ALA residues in chain A
"//A/*/!CA,CB"                 # All atoms except CA and CB in chain A
"//A/*/[!H]"                   # All non-hydrogen atoms in chain A

Examples

# Select entire chain
"//A"                          # All atoms in chain A
"//A,B,C"                      # All atoms in chains A, B, and C

# Select residue range
"//A/12-130"                   # Residues 12-130 in chain A
"//A/12-130/CA"                # CA atoms from residues 12-130 in chain A
"//A/33.A-120.B"               # Residue range with insertion codes

# Select by residue type
"//B/10-20(GLY)"               # GLY residues 10-20 in chain B
"//A/*(HIS)"                   # All HIS residues in chain A
"//A/(GLU,ASP)"                # All glutamate and aspartate in chain A
"//A/(!ALA,GLY)"               # All residues except ALA and GLY in chain A

# Select specific atom
"//A/50/CA"                    # CA atom of residue 50 in chain A
"//A/50(HIS)/CA"               # CA atom of HIS 50 in chain A

# Element disambiguation
"CA[C]"                        # C-alpha atoms (carbon), not calcium
"//A/*/[C]"                    # All carbon atoms in chain A
"//A/*/[!H]"                   # All non-hydrogen atoms in chain A

# Alt-loc selection
"//A/50/CA:A"                  # CA in alt-loc A
"[C]:,A"                       # Carbons with no alt-loc or alt-loc A

# Wildcards
"*"                            # All atoms in the structure
"/1"                           # All atoms in model 1
"33-120"                       # Residues 33-120 in any chain

Note: Selections containing commas must be quoted.

Usage Examples

# Create a new molecule with chains A and B
imol_ab = coot.new_molecule_by_atom_selection(0, "//A,B")

# Create a new molecule with CA atoms from residues 10-50 in chain A
imol_ca = coot.new_molecule_by_atom_selection(0, "//A/10-50/CA")

# Superpose using CA atoms
coot.superpose_with_atom_selection(
    imol1=0,
    imol2=1,
    mmdb_atom_sel_str_1="//A/10-100/CA",
    mmdb_atom_sel_str_2="//A/10-100/CA",
    move_imol2_copy_flag=0
)

# Hydrogen bonds between a residue and a chain
coot.get_hydrogen_bonds_py(0, "//A/35", "//A", 0)

Code Execution Patterns

Single-line expressions

Single-line expressions return their evaluated value:

coot.is_valid_model_molecule(0)  # Returns: 1 or 0

Multi-line code blocks

Multi-line blocks require explicit return or final expression:

# ❌ This returns None (print doesn't return a value)
mols = []
for i in range(3):
    mols.append(i)
print(mols)

# ✅ CORRECT: Return the value or use final expression
mols = []
for i in range(3):
    mols.append(i)
mols  # Final expression is returned

# ✅ ALSO CORRECT: List comprehension (single expression)
[i for i in range(3)]

Common Tasks Reference

Loading Tutorial Data

# ✅ CORRECT function name
coot.load_tutorial_model_and_data()

# ❌ INCORRECT function names that don't exist
# coot.tutorial_model_and_data()  # Wrong!

Listing Molecules

# Check molecules 0-5
[(i, coot.is_valid_model_molecule(i), coot.is_valid_map_molecule(i)) for i in range(6)]

# Get molecule names for valid molecules
for i in range(10):
    if coot.is_valid_model_molecule(i):
        print(f"Model {i}: {coot.molecule_name(i)}")
    elif coot.is_valid_map_molecule(i):
        print(f"Map {i}: {coot.molecule_name(i)}")

Working with Chain IDs

# ✅ CORRECT: Use coot_utils for convenience
import coot_utils
chains = coot_utils.chain_ids(0)  # Returns: ['A', 'B', 'C']

# Iterate over chains
for chain in chains:
    print(f"Chain {chain}")

Getting Active/Closest Residue

# ✅ Get closest atom across displayed molecules
atom = coot.closest_atom_simple_py()
if atom:
    imol, chain, resno, ins, atom_name, alt, coords = atom[0], atom[1], atom[2], atom[3], atom[4], atom[5], atom[6]

# ✅ Get active residue (with potential CA substitution)
import coot_utils
active = coot_utils.active_residue()
if active:
    imol, chain, resno, ins, atom_name, alt = active

Density Fit Analysis

Map Correlation Functions

# Get correlation for specific residues
import coot_utils

# Single residue
residue_spec = ["A", 42, ""]
correlation = coot.density_score_residue_py(0, residue_spec, 1)

# Per-residue correlation for a range
residue_specs = [["A", i, ""] for i in range(40, 50)]
results = coot.map_to_model_correlation_per_residue_py(0, residue_specs, 0, 1)
# Returns: [(residue_spec, correlation), ...]

# Main function for "which residue fits worst?"
stats = coot.map_to_model_correlation_stats_per_residue_range_py(
    0, "A", 1, 100, 1  # imol, chain, start, end, imol_map
)

Zoom and View Settings

When adjusting the view in Coot, remember that higher zoom values mean the molecule appears larger on screen (i.e., zoomed in), while lower values show more of the scene (zoomed out). Typical ranges:

• 150-300: Whole-molecule overview (appropriate for ribbons, surfaces, overall architecture)
• 50-100: Domain or region level
• 20-50: Residue-level detail (inspecting side chains, density fit, rotamers)

Small proteins like RNase A (~124 residues) may appear compact even at zoom 200, while larger complexes will fill the screen at lower zoom values. When presenting a ribbon diagram or other overview representation, consider turning off the bond representation (coot.set_mol_displayed(imol, 0)) and hiding electron density maps (coot.set_map_displayed(imol_map, 0)) to reduce visual clutter while keeping the ribbon mesh visible.

Use coot.zoom_factor() to query the current zoom level and coot.set_zoom(value) to set it. For interactive exploration, users can also adjust zoom with the scroll wheel.

Performance Considerations

Function Call Overhead

# ❌ SLOW: Multiple function calls through Python wrapper
import coot_utils
for i in range(1000):
    atom = coot_utils.closest_atom(0)  # Unnecessary indirection

# ✅ FAST: Direct C++ calls
for i in range(1000):
    atom = coot.closest_atom_py(0)

When Python Wrappers Are Worth It

Python wrappers are valuable when they:

1. Aggregate multiple C++ calls (e.g., chain_ids() calls chain_id_py() in a loop)
2. Transform data into more convenient formats
3. Provide meaningful abstractions that simplify complex operations
4. Add error handling or validation logic

Decision Tree

Need to call a Coot function?
│
├─ Does it require coot_utils for convenience features?
│  └─ YES → import coot_utils and use it
│     Examples: chain_ids(), active_residue()
│
└─ NO → Use coot.*_py() directly
   Examples: closest_atom_simple_py(), is_valid_model_molecule()

Quick Reference Table

Task	❌ Avoid	✅ Use Instead	Reason
Get closest atom (all molecules)	coot_utils.closest_atom_simple()	coot.closest_atom_simple_py()	Direct C++, no import needed
Get closest atom (specific mol)	coot_utils.closest_atom(imol)	coot.closest_atom_py(imol)	Direct C++, no import needed
Get chain IDs	Multiple C++ calls	coot_utils.chain_ids(imol)	Convenience wrapper adds value
Check if valid model	coot_utils.valid_model_molecule_qm()	coot.is_valid_model_molecule(imol)	Direct C++, clearer name
Get molecule name	N/A	coot.molecule_name(imol)	Direct C++ only
Load tutorial data	coot.tutorial_model_and_data()	coot.load_tutorial_model_and_data()	Correct function name

Common Mistakes to Avoid

1. Using coot_utils without import

# ❌ Will fail with NameError
chains = coot_utils.chain_ids(0)

# ✅ Import first
import coot_utils
chains = coot_utils.chain_ids(0)

2. Using coot_utils when unnecessary

# ❌ Unnecessary indirection
import coot_utils
atom = coot_utils.closest_atom_simple()

# ✅ Direct and faster
atom = coot.closest_atom_simple_py()

3. Wrong function names

# ❌ Function doesn't exist
coot.tutorial_model_and_data()

# ✅ Correct name
coot.load_tutorial_model_and_data()

4. Getting output from multi-line code

# ✅ Use print() to see output - it appears in stdout
result = []
for i in range(5):
    result.append(i)
print(result)  # Output: [0, 1, 2, 3, 4]

# ❌ A bare expression at the end of multi-line code does NOT return a value
result = []
for i in range(5):
    result.append(i)
result  # Returns None - this doesn't work!

## API Discovery Tools

### Using search_coot_functions

The `search_coot_functions` tool is your primary method for finding Coot functions. It supports powerful search patterns:

**Space-separated words = Logical AND**
```python
# Find functions containing ALL these words
search_coot_functions("map model correlation")
# Returns functions like: map_to_model_correlation_stats_per_residue_range_py

search_coot_functions("residue range chain")
# Returns functions dealing with residue ranges in chains

search_coot_functions("min max residue")
# Returns functions with all three words (not just any one)

Single words = Simple search

search_coot_functions("correlation")  # All functions with "correlation"
search_coot_functions("validation")   # All functions with "validation"
search_coot_functions("rotamer")      # All functions with "rotamer"

Common search patterns:

• "map correlation" - density fit functions
• "residue validation" - geometry checking
• "chain residue" - chain/residue operations
• "ligand environment" - ligand analysis
• "ramachandran" - backbone validation
• "density fit" - map fitting functions

✅ CORRECT Search Strategy

# Looking for functions to get residues in a chain
search_coot_functions("chain residue")  # Logical AND

# Looking for min/max residue number functions
search_coot_functions("min max residue")  # All three words required

# Looking for correlation analysis
search_coot_functions("correlation residue")  # Both words required

❌ INCORRECT Search Strategy

# DON'T use grep with pipe (|) when you mean AND
# This searches for min OR max OR residue (logical OR)
# Use search_coot_functions with spaces instead

When to use each discovery tool

1. search_coot_functions(pattern) - First choice

   • Use space-separated words for AND logic
   • Returns max 40 results with documentation
   • Best for targeted searches

2. list_coot_categories() - For browsing

   • Returns: ['load', 'read', 'display', 'refinement', 'validation', 'ligand', 'util']
   • Use when you want to explore a general area

3. get_functions_in_category(category) - For comprehensive lists

   • Returns all functions in a category (50-200 functions)
   • Use after identifying the right category

Search Tips

• Start with 2-3 specific words that describe what you need
• If too many results, add more words to narrow down
• If no results, try synonyms or broader terms
• Common terms: validation, correlation, residue, chain, map, model, ligand, fit, geometry

Summary

1. Always prefer coot.*_py() functions when they're simple passthroughs
2. Only use coot_utils functions when they add genuine convenience
3. Remember coot is auto-imported, coot_utils is not
4. Use single-line expressions when possible for cleaner returns
5. Check function names - load_tutorial_model_and_data() not tutorial_model_and_data()
6. Use search_coot_functions with space-separated words for AND logic when searching the API

Following these practices ensures optimal performance and correct API usage when working with Coot through the MCP server.