mmtbx - macromolecular crystallography

The mmtbx module has two purposes: firstly, it introduces additional crystallographic algorithms that are traditionally specific to macromolecular structures, such as bulk-solvent correction, absolute scaling, maximum likelihood targets, non-crystallographic symmetry, weighted maps, and real-space refinement; and secondly, it provides many higher-level classes for querying and manipulating molecular structures and writing full-featured macromolecular crystallography applications. Most of the core functions of the program phenix.refine are part of mmtbx, and the module also includes the complete code for the programs phenix.xtriage, phenix.maps, phenix.ensemble_refinement, phenix.model_vs_data, and phenix.pdbtools, plus the backend logic for the MolProbity server.

For new developers, the module mmtbx.command_line provides a simplified frontend for running routine setup tasks (such as bulk solvent correction or geometry restraints interpretation) and populating many of the standard data structures. (The source code also provides a suitable example should you wish to instantiate these objects yourself.) However, since the resulting objects tend to be especially complex, some knowledge of their internals and purpose is helpful.

The most important modules in mmtbx can be summarized as follows:

  • mmtbx.f_model: encapsulates most functionality for calculating F(model) (i.e. F(calc)) and comparing it against experimental data. The calculation of weighted electron density maps usually starts from this point.
  • mmtbx.monomer_library.pdb_interpretation: processing of models (in PDB or mmCIF format) and interpretation with respect to a library of geometry restraints (provided as part of Phenix, but the CCP4 Monomer Library may also be used).
  • mmtbx.scaling: absolute scaling routines plus analyses of experimental data to assess quality and detect possible pathologies such as twinning. This module is slightly misnamed, since it is primarily used as the backend for Xtriage.
  • mmtbx.validation: tools for assessing model quality, based either on geometric criteria or fit to data. Also see mmtbx.rotamer, the lower-level code for analyzing conformation.
  • mmtbx.refinement: routines for model optimization against either reciprocal space or real-space (i.e. electron density map) data.
  • mmtbx.pdbtools: a small library (as well as a standalone program) for various common model manipulations.



Module contents

class mmtbx.fmodels(fmodel_xray=None, fmodel_neutron=None, xray_scattering_dict=None, neutron_scattering_dict=None, neutron_refinement=None, twin_law=None, log=None)

Bases: object

Container object for F_model values used during refinement.


fmodel_xray :  
fmodel_neutron :  
xray_scattering_dict :  
neutron_scattering_dict :  
neutron_refinement :  
twin_law :  


create_target_functors() ...
fmodel_neutron([xray_structure]) ...
fmodel_xray([xray_structure]) ...
prepare_target_functors_for_minimization() ...
pseudo_deep_copy() Makes a deep copy of self.
resolution_filter(d_min) Returns a copy of self with a resolution filter applied to the x-ray and neutron maps above a given resolution.
show_comprehensive([message]) ...
show_short([log]) ...
show_targets(log[, text]) ...
target_and_gradients(weights, compute_gradients) ...
target_functions_are_invariant_under_allowed_origin_shifts() ...
target_functor_result_neutron(compute_gradients) ...
target_functor_result_xray(compute_gradients) ...
update([target_name]) ...
update_all_scales(update_f_part1[, ...]) ...
update_xray_structure([xray_structure, ...]) ...









Makes a deep copy of self.


Returns a copy of self with a resolution filter applied to the x-ray and neutron maps above a given resolution.


d_min : float

Reflections with resolutions <= d_min are removed.







show_targets(log, text='')


target_and_gradients(weights, compute_gradients, u_iso_refinable_params=None, occupancy=False)










update_all_scales(update_f_part1, remove_outliers=True, params=None, optimize_mask=False, force_update_f_mask=False, nproc=1, log=None, apply_back_trace=False, refine_hd_scattering=None)


update_xray_structure(xray_structure=None, update_f_calc=None, update_f_mask=None, force_update_f_mask=False)


class mmtbx.map_names(map_name_string)

Bases: object

Class used for parsing and external display of map’s name.


k (float) Scale for F_obs.
n (float) Scale for F_model.
ml_map (bool)
anomalous (bool)
anomalous_residual (bool)
phaser_sad_llg (bool)
kicked (bool)
f_obs_filled (bool)


error(s) Raises an exception for bad map names.
format() Formats a map name for external display.
DFC = ['dfcalc', 'dfcal', 'dfc', 'dfmodel', 'dfmod', 'dfm']
FC = ['fcalc', 'fcal', 'fc', 'fmodel', 'fmod', 'fm']
FILLED = ['+filled', '-filled', 'filled', '+fill', '-fill', 'fill']
FO = ['fobs', 'fob', 'fo']
KICK = ['-kicked', '+kicked', 'kicked', '-kick', '+kick', 'kick']
MFO = ['mfobs', 'mfob', 'mfo']

Raises an exception for bad map names.


Formats a map name for external display.


>>> r = mmtbx.map_names(map_name_string="mFo-DFc ")
>>> print r.format()

Table Of Contents

Next topic

mmtbx.building package

This Page