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 coot.set_refinement_immediate_replacement() before using refinement functions (just once is enough) which should remove the risk of threading conflicts and crashes, race conditions between refinement and rendering.

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

1. Enable immediate replacement

coot.set_refinement_immediate_replacement(1)

coot.set_imol_refinement_map(imol_map)

3. Refine residues (preferred method)

Pass a list of residue specs: [[“A”, 42, “”], [“A”, 43, “”], …]

residue_specs = [[“A”, resno, “”] for resno in range(start_resno, end_resno + 1)] result = coot.refine_residues_py(imol, residue_specs)

4. so-called “sphere refine” is often useful because it allows movement/improvement

of residues that are close in space but distant in sequence.

central_residue_spec = [‘A’, 12, ‘’] neigbs = coot.residues_near_residue(imol, central_residue_spec) residue_spec = neigbs residue_specs.append(central_residue_spec) result = coot.refine_residues_py(imol, residue_specs)

# 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

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}")

Refining with Secondary Structure Restraints

When adding residues in a known secondary structure conformation (e.g. a helix or strand), use set_secondary_structure_restraints_type() to maintain that geometry during real-space refinement. Without this, refine_residues_py() treats residues independently and the conformation can distort away from the intended geometry if the density doesn’t strongly support it.

Secondary structure restraint types

0 — no restraints (default)
1 — alpha helix (restrains i→i+4 hydrogen bond geometry)
2 — beta strand

# Set BEFORE refinement
coot.set_secondary_structure_restraints_type(1)  # 1 = alpha helix

coot.refine_residues_py(imol, residue_specs)

# Reset AFTER refinement - critical, or all subsequent refinements
# will use helix restraints unintentionally
coot.set_secondary_structure_restraints_type(0)

Example: add and refine a 6-residue helix

coot.set_refinement_immediate_replacement(1)
coot.set_secondary_structure_restraints_type(1)

residue_specs = [["A", resno + i, ""] for i in range(6)]
coot.refine_residues_py(imol, residue_specs)

coot.set_secondary_structure_restraints_type(0)

Common mistake

Calling refine_residues_py() directly after building helical residues without setting the restraint type — the helix geometry will not be maintained during refinement.

Common Functions

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

Coot Refinement Best Practices