Coot Refinement Best Practices

This skill provides guidance for effective and safe structure refinement in Coot, based on lessons learned from crashes and workflow optimization.

Critical Configuration

Set Immediate Replacement Mode for Scripting

ALWAYS call this before any refinement operations in scripts:

coot.set_refinement_immediate_replacement(1)

Why: Enables synchronous operation where refinement directly updates coordinates. Without this:

• Refinement happens asynchronously in background threads
• Need to call accept_moving_atoms_py() after each operation
• Risk of threading conflicts and crashes
• Race conditions between refinement and rendering

When to use: Any time you're scripting refinement operations (auto_fit_best_rotamer, refine_zone, etc.)

Safe Refinement Workflow

Single Residue Refinement

# 1. Enable immediate replacement
coot.set_refinement_immediate_replacement(1)

# 2. Fix rotamer
coot.auto_fit_best_rotamer(
    residue_cid,
    "",  # alt conf
    imol,
    imol_map,
    1,   # use ramachandran restraints
    0.1  # rama weight
)

# 3. Refine in context (sphere refinement)
coot.refine_residues_using_atom_cid(
    imol,
    residue_cid,
    "SPHERE",
    4000  # radius
)

# No need for accept_moving_atoms_py() with immediate replacement!

Zone Refinement

# Enable immediate replacement
coot.set_refinement_immediate_replacement(1)

# Refine zone
coot.refine_zone(
    imol,
    chain_id,
    start_resno,
    end_resno,
    ""  # alt conf
)

Validation and Correlation

Check Residue Quality

# Get density correlation for specific residue
correlation = coot.density_correlation_analysis_scm(imol, chain_id, resno, ins_code)
# Returns dict with 'all-atom' and 'side-chain' correlations

# Get worst residues
worst = coot.get_n_residues_with_worst_density_fit(imol, n_residues)
# Returns list of [chain_id, resno, inscode, correlation]

Correlation Targets

Good fit:

• All-atom correlation: > 0.8
• Side-chain correlation: > 0.8

Poor fit (needs attention):

• All-atom correlation: < 0.5
• Side-chain correlation: < 0.5

Common Crash Scenarios to Avoid

Threading/Rendering Conflicts

Problem: Rapid-fire refinement operations while graphics are rendering can cause memory corruption in GTK rendering pipeline.

Symptoms:

nanov2_guard_corruption_detected
gdk_gl_texture_new_from_builder
gtk_gl_area_snapshot

Solution: Use set_refinement_immediate_replacement(1) for synchronous operation

Asynchronous Refinement Without Accept

Problem: Refinement starts but coordinates aren't committed before next operation.

Solution: Either:

1. Use immediate replacement mode (recommended)
2. OR call accept_moving_atoms_py() after each refinement

Multi-Line Code Limitation

Coot only returns values if code is a single line:

Doesn't work:

x = 5
y = 10
x + y  # Won't return value

Workaround:

# Call 1: Define function
def calculate():
    x = 5
    y = 10
    return x + y

# Call 2: Execute function
calculate()  # Returns 15

Systematic Residue Fixing Workflow

# 1. Enable immediate replacement
coot.set_refinement_immediate_replacement(1)

# 2. Find worst residues
worst = coot.get_n_residues_with_worst_density_fit(0, 10)

# 3. For each poor residue:
for residue in worst:
    chain_id, resno, inscode, corr = residue
    
    # Build CID
    cid = f"//{chain_id}/{resno}"
    
    # Try rotamer fix
    coot.auto_fit_best_rotamer(cid, "", 0, 1, 1, 0.1)
    
    # Refine in context
    coot.refine_residues_using_atom_cid(0, cid, "SPHERE", 4000)
    
    # Check improvement
    new_corr = coot.density_correlation_analysis_scm(0, chain_id, resno, inscode)
    print(f"{cid}: {corr:.3f} → {new_corr['all-atom']:.3f}")

Common Functions

Refinement

• auto_fit_best_rotamer(cid, alt_conf, imol, imol_map, use_rama, rama_weight) - Fix rotamer
• refine_residues_using_atom_cid(imol, cid, mode, radius) - Sphere/zone refinement
• refine_zone(imol, chain, start, end, alt_conf) - Refine residue range
• set_refinement_immediate_replacement(istate) - Enable synchronous refinement

Validation

• density_correlation_analysis_scm(imol, chain, resno, inscode) - Get correlation
• get_n_residues_with_worst_density_fit(imol, n) - Find problem residues

Other

• pepflip(imol, atom_cid, alt_conf) - Flip peptide