PROPOSED CIF ITEMS DESCRIBING CONSTRAINTS AND RESTRAINTS  2007-12-12

This file contains a PROPOSAL for the CIF encoding of details of the restraints and constraint used during the refinement of a crystal structure.  
It has been prepared by David Brown and Ilia Guzei.

idbrown@mcmaster.ca
iguzei@chem.wisc.edu

INTRODUCTION

This proposal for including information on restraints and constraints in CIF is
presented at this stage in the form of a CIF rather than dictionary code as this is simpler to follow and easier to understand.  
After the draft has received a general endorsement, the full CIF dictionary code 
will be developed.  
For the most part the CIF data names are self-explanatory but where further 
information is need, explanations are given in the form of comments inserted into the CIF.  
These comments will be incorporated into the final dictionary code.

The following principles were kept in mind when creating the present draft. 

1. Over the years there has been a number of requests for a 
method of CIF-recording the details of restraints and 
constraints that were applied during the refinement of a 
crystal structure.  Some have suggested that this could be 
most easily achieved by dumping the program instruction file 
into a text field in the CIF.  However, this violates an important 
CIF principle, namely that a CIF together with its dictionary should 
contain everything needed to interpret and understand the contents 
of the CIF.  Including an instruction file for a proprietary program 
does not meet this criterion because the instructions can only be 
interpreted with the aid of the relevant program manual.  If the 
program falls out of use, the manual may no longer be available. 

The CIF standard is compatible with and recognized by a large number
of programs and is supported by the IUCr with the intention that
it will be stable for the foreseeable future. 
Therefore we are supplying CIF definitions for many of the basic 
restraints and constraints that are currently in use knowing that
the CIF dictionaries will provide a community-wide standard whose 
definitions are readily accessible, e.g., in enCIFer and publCIF.

2. The items defined are chosen to be as generic as possible so that they are not dependent on the particular way in which the restraint or constraint is applied.

3. We have assumed that these items will only be used to report restraints that
have already been applied.  We do not anticipate that they will be used as
instructions to programs to perform a restrained refinement.  This simplifies
the programming as it is only necessary to write software that will convert
the restraint instructions into the CIF format.  No code will be needed to
convert the information given in the CIF into the closest available restraint 
within the refinement program.

12-Dec-07 IG:  I would like the introduced CIF entries to be sufficient to allow someone to reproduce the refinement.  And I would rephrase  ?We do not anticipate that they will be used as instructions to programs to perform a restrained refinement.? to reflect this fact:  ?The proposed entries will be sufficient to reproduce the refinement if desired? or something to this effect. 

4. From the comments we received on our first draft circulated to the managers of various commonly-used structure-solving programs, we have come to appreciate 
how wide a range of restraint and constraint options is available in 
different programs, some restraints being quite sophisticated.  We have 
not attempted to provide CIF code for all of these; we have focused 
on just the basic restraints, but we are also proposing a catch-all text 
field that can be used to describe the more complex restraints which currently
cannot be adequately described using the more specific items defined 
here. 

5. We have emphasised primitives.  For example, rigid bodies can be defined and programmed in many ways.  The simplest and most elegant approach to recording this in CIF is to introduce a flag in atom_site that links all the atoms belonging to the same rigid body.  No further description is needed as the input target geometry is the same as the refined geometry reported in the CIF.  This method of reporting a rigid body provides flexibility as it makes no assumptions about how the rigid body is treated in the program.  Furthermore, this description can be expanded in the future to allow for reporting rigid body dynamics.  

6. The relative weight assigned to a restraint is defined in each case 
by a weighting parameter which is the expectation value of the difference
between the target and the refined value.  It is comparable to a standard 
uncertainty.  It is related to the weight by the equation:

               weighting parameter = sqrt(1/weight) 

and has the advantage of having the same units as the target and being 
easy to relate to the actual difference between the refined value and the target

7. Constraints are reported in the same way as restraints but with the
weighting parameter set to 0.  This can be treated as a flag - if the 
weighting parameter is zero the condition is a constraint; if it is not
zero it is a restraint.  This convention provides flexibility and reduces 
the number of items that need to be defined.


###################################################################################

#                   TABLE OF CONTENTS
#
# RESTRAINT 1. A DISTANCE IS RESTRAINED TO A PREDETERMINED VALUE. 
#                                                          restr_distance
# RESTRAINT 2. AN ANGLE IS RESTRAINED TO A PREDETERMINED VALUE. 
#                                                          restr_angle
# RESTRAINT 3, A TORSION ANGLE IS RESTRAINED TO A PREDETERMINED VALUE.
#                                                          restr_torsion
# RESTRAINT 4. SEVERAL DISTANCES ARE RESTRAINED TO BE EQUAL. 
#                                                          restr_equal_distance
# RESTRAINT 5. SEVERAL ANGLES ARE RESTRAINED TO BE EQUAL. 
#                                                          restr_equal_angle
# RESTRAINT 6. SEVERAL TORSION ANGLES ARE RESTRAINED TO BE EQUAL.
#                                                          restr_equal_torsion
# RESTRAINT 7. A GROUP OF ATOMS IS RESTRAINED TO LIE ON A PLANE. 
#                                                          restr_plane         
# RESTRAINT 8. ADPs ARE RESTRAINED FOR A RIGID BOND. 
#                                                          restr_U_rigid
# RESTRAINT 9. ATOMS CANNOT OCCUPY THE SAME POSITION
#                                                          restr_distance_min
# RESTRAINT 10. THE SUM OF A GIVEN PARAMETER OF THE SPECIFIED ATOMS IS  
#                RESTRAINED                                restr_parameter
# RESTRAINT 11. RIGID BODY
#                                                          restr_rigid
# RESTRAINT 12. TEXT DESCRIPTION OF OTHER RESTRAINTS
#                                                          restr


# ----------------------------------------------------------------------------
# RESTRAINT 1. A DISTANCE IS RESTRAINED TO A PREDETERMINED VALUE. 
# ----------------------------------------------------------------------------



loop_         # category name restr_distance
              # The first four items form the category key
_restr_distance_atom_site_label_1   
_restr_distance_site_symmetry_1
_restr_distance_atom_site_label_2
_restr_distance_site_symmetry_2
_restr_distance_target
_restr_distance_target_weight_param
              # weighting parameter = sqrt(1/weight).  It is the expectation value 
              # of the difference between the refined value and the target. 
_restr_distance_diff      
              # difference between target and refined values
_restr_distance_details
C1  1_555 C2  1_555  1.524  0.04 -0.032 'generated by SHELX DFIX'
C2  1_555 C3  1_555  1.340  0.04  0.051 'generated by SHELX DFIX'
Na1 1_555 Ca1 1_555  0.0    0.0   0.0 
'Na1, Fe1 and Al1 are constrained to the same site. generated by SHELX EXYZ'
Fe1 1_555 Ca1 1_555  0.0    0.0   0.0  
'Na1, Fe1 and Al1 are constrained to the same site. generated by SHELX EXYZ'
Al1 1_555 Ca1 1_555  0.0    0.0   0.0  
'Na1, Fe1 and Al1 are constrained to the same site. generated by SHELX EXYZ'
#
#
#
# ----------------------------------------------------------------------------
# RESTRAINT 2. AN ANGLE IS RESTRAINED TO A PREDETERMINED VALUE. 
# ----------------------------------------------------------------------------

loop_         # category name restr_angle
              # The first six items form the category key
_restr_angle_atom_site_label_1   
_restr_angle_site_symmetry_1
_restr_angle_atom_site_label_2  # atom 2 is at the apex of the angle
_restr_angle_site_symmetry_2
_restr_angle_atom_site_label_3
_restr_angle_site_symmetry_3
_restr_angle_target
_restr_angle_target_weight_param
              # weighting parameter = sqrt(1/weight)  It is the expectation value 
              # of the next item
_restr_angle_diff      
              # difference between target and refined values
_restr_angle_details
C1 1_555  C2  1_555  C3 1_555 120  1   -0.3 'generated by JANA'
C2 1_555  C3  1_555  C4 3_455 120  1.5  0.5 ?



# ----------------------------------------------------------------------------
# RESTRAINT 3. A TORSION ANGLE IS CONSTRAINED TO A PREDETERMINED VALUE
# ----------------------------------------------------------------------------

loop_           # category name restr_torsion
                # the first eight items constitute the category key
_restr_torsion_atom_label_1
_restr_torsion_site_symmetry_1  
_restr_torsion_atom_label_2
_restr_torsion_site_symmetry_2
_restr_torsion_atom_label_3
_restr_torsion_site_symmetry_3
_restr_torsion_atom_label_4
_restr_torsion_site_symmetry_4
_restr_torsion_angle
_restr_torsion_weight_param
_restr_torsion_diff
_restr_torsion_details  
Na1 1_555  Na1 2_555  O1 2_555  H101 1_555  90  1  0.97  ?


# ----------------------------------------------------------------------------
# RESTRAINT 4. SEVERAL DISTANCES ARE RESTRAINED TO BE EQUAL. 
# ----------------------------------------------------------------------------
# This item, and the two following contain two loops.
# The purpose of the second loop is to allow the introduction
# of classes which permit this restraint to be applied independently
# to different groups of distances.
# --------------------------------------------------------
loop_         # category name restr_equal_distance
              # The first four items form the category key 
_restr_equal_distance_atom_site_label_1   
_restr_equal_distance_site_symmetry_1  
_restr_equal_distance_atom_site_label_2
_restr_equal_distance_site_symmetry_2
_restr_equal_distance_class_id
_restr_equal_distance_details    
C1 1_555  C2  1_555  1  'C1-C2 and C3-C4 are restrained to be equal'
C2 1_555  C3  1_555  2  'C2-C3, C4-C5 and C5-C6 are restrained to be equal'
C3 1_555  C4  2_655  1  ?
C4 1_555  C5  1_555  2  ?
C5 1_555  C6  1_555  2  ?


loop_         # Category name restr_equal_distance_class
_restr_equal_distance_class_class_id        
              # category key, must be the same as
              # _restr_equal_distance_class_id
_restr_equal_distance_class_target_weight_param
              # weighting parameter. Expectation value of _*_esd.
_restr_equal_distance_class_average   
              # average bond length of the class after refinement
_restr_equal_distance_class_esd      
              # estimated standard deviation of the set of bonds in the class
_restr_equal_distance_class_diff_max  
              # maximum deviation from the average
_restr_equal_distance_class_details   

1  0.04   1.534  0.032  0.053   ?
2  0.04   1.338  0.052  0.103   ?

#
#
# ----------------------------------------------------------------------------
# RESTRAINT 5. SEVERAL ANGLES ARE RESTRAINED TO BE EQUAL. 
# ----------------------------------------------------------------------------

loop_         # category name restr_equal_angle
              # The first six items form the category key 
_restr_equal_angle_atom_site_label_1   
_restr_equal_angle_site_symmetry_1
_restr_equal_angle_atom_site_label_2   # Atom 2 is at the apex of the angle
_restr_equal_angle_site_symmetry_2
_restr_equal_angle_atom_site_label_3   
_restr_equal_angle_site_symmetry_3
_restr_equal_angle_class_id
_restr_equal_angle_details
C1 1_555  C2  1_555  C3 1_555 1  'Benzene ring with mirror symmetry' 
C2 1_555  C3  1_555  C4 2_655 2  ? 
C4 1_555  C5  1_555  C6 1_555 2  ?
C5 1_555  C6  1_555  C1 1_555 1  ?

loop_         # Category name restr_equal_angle_class
_restr_equal_angle_class_class_id        
              # category key, must be the same as
              # _restr_equal_angle_class_id
_restr_equal_angle_class_target_weight_param
              # weighting parameter
_restr_equal_angle_class_average   
              # average bond angle of the class after refinement
_restr_equal_angle_class_esd      
              # estimated stsndard deviation of the set of angles in the class
_restr_equal_angle_class_diff_max  
              # maximum deviation from the average

_restr_equal_angle_class_details
1  0.50  123.52  0.32 0.62  ?
2  0.50  118.23  0.52 1.43  ?

#
#
# ----------------------------------------------------------------------------
# RESTRAINT 6. SEVERAL TORSION ANGLES ARE RESTRAINED TO BE EQUAL. 
# ----------------------------------------------------------------------------

loop_         # category name restr_equal_torsion
              # The first eight items form the category key 
_restr_equal_torsion_atom_site_label_1   
_restr_equal_torsion_site_symmetry_1
_restr_equal_torsion_atom_site_label_2   
_restr_equal_torsion_site_symmetry_2
_restr_equal_torsion_atom_site_label_3   
_restr_equal_torsion_site_symmetry_3
_restr_equal_torsion_atom_site_label_4
_restr_equal_torsion_site_symmetry_4
_restr_equal_torsion_class_id
_restr_equal_torsion_details
C1 1_555  C2  1_555  C3 1_555  C4 1_555 1 ?
C5 1_555  C6  1_555  C1 1_555  C2 1_555 1 ?


loop_         # Category name restr_equal_torsion_class
_restr_equal_torsion_class_class_id        
              # category key, must be the same as
              # _restr_equal_torsion_class_id
_restr_equal_torsion_class_target_weight_param
              # weighting parameter
_restr_equal_torsion_class_average   
              # average bond angle of the class after refinement
_restr_equal_torsion_class_esd      
              # esd of the set of angles in the class
_restr_equal_torsion_class_diff_max  
              # maximum deviation from the average
_restr_equal_torsion_class_details

1  0.50  123.52  0.32  0.62 ?

# ----------------------------------------------------------------------------
# RESTRAINT 7. A GROUP OF ATOMS IS RESTRAINED TO LIE ON A PLANE.
# ----------------------------------------------------------------------------

loop_           # category name restr_plane
                # The first three items are the category key 
_restr_plane_atom_site_label 
_restr_plane_site_symmetry  
_restr_plane_class_id       
                # A different class_id is used for different planes
_restr_plane_target_weight_param
_restr_plane_displacement   
                # this is the deviation from the plane after refinement
_restr_plane_details
c1 1_555 1 0.02  0.002(1) 'C1 to C4 lie on one plane'  
c2 1_555 1 0.02 -0.003(2) ?
c3 1_555 1 0.02 -0.002(1) ?
c4 1_555 1 0.02  0.002(2) ?
c1 2_655 2 0.003  0.004(1) 'c1, c5, c6 and c7 lie on one plane'
c5 1_555 2 0.003 -0.002(2) ?
c6 1_555 2 0.003  0.002(3) ?
c7 1_555 2 0.003 -0.002(2) ?


loop_            # category name restr_plane_class
_restr_plane_class_class_id     
                 # category key
                 # value must correspond to _restr_plane_class_id
_restr_plane_class_displacement_esd      
                 # estimated standard deviation of the set of 
                 # displacements between plane and atoms
_restr_plane_class_displacement_max_atom_site_label
_restr_plane_class_displacement_max_site_symmetry
_restr_plane_class_displacement_max
_resrt_plane_class_details

1  0.032  c2 1_555  0.094     'displacements for plane 1'
2  0.0021 c1 2_655  0.010     'displacements for plane 2'
#
# ----------------------------------------------------------------------------
# RESTRAINT 8. ADPs ARE RESTRAINED FOR A RIGID BOND. 
# ----------------------------------------------------------------------------

#  This "rigid bond" restraint restrains the anisotropic displacement
#  parameters of two atoms to be equal within a certain _weight_param along the 
#  direction of the vector joining the atoms.


loop_        # category name  _restr_U_rigid
             # The first four items form the category key 
_restr_U_rigid_atom_site_label_1  
_restr_U_rigid_site_symmetry_1  
_restr_U_rigid_atom_site_label_2
_restr_U_rigid_site_symmetry_2
_restr_U_rigid_target_weight_param
              # weighting parameter expressed in terms of U.
_restr_U_rigid_U_parallel
              # Average component of U parallel to the bond
_restr_U_rigid_diff
              # Difference in the components of U parallel to the bond
_restr_U_rigid_details
C1 1_555 C2 2_655 0.001 0.0023(2) 0.0006 'C1-C2 is a rigid bond'

#
#
# ----------------------------------------------------------------------------
# RESTRAINT 9. ATOMS CANNOT OCCUPY THE SAME POSITION
# ----------------------------------------------------------------------------
# The "anti-bumping" restraints would normally be reported only for those distances 
# in which this restraint was invoked. 


loop_         # category name is restr_distance_min
              # The first four items form the category key
_restr_distance_min_atom_site_label_1  
_restr_distance_min_site_symmetry_1
_restr_distance_min_atom_site_label_2
_restr_distance_min_site_symmetry_2
  # The weight associated with the difference between the refined distance D and 
  # the prescribed minimum distance (B or F) is:
  #   w = A*(B/D)^C + E*exp((F-D)/G)
  # Either function could be used alone by setting A or E to zero.
  # The default values of A and E are zero.
  # If A=0, B and C are undefined, if E=0, F and G are undefined
  # A hard sphere contact could be generated by setting E=1, 
  # F=prescribed minimum distance and G=0.  This is not a correct mathematical
  # description but G could be regarded as a flag for the hard sphere constraint.
_restr_distance_min_A
_restr_distance_min_B
_restr_distance_min_C
_restr_distance_min_E
_restr_distance_min_F
_restr_distance_min_G
_restr_distance_min_distance
_restr_distance_min_details
O1 1_555 O2 1_555 0 . . 1 2.8 0.3 2.75(1) 'using the exponential restraint'
O2 1_555 O3 2_455 0 0 0 1 2.8 0   2.83(1) 'using the hard sphere model'
#
#
# ----------------------------------------------------------------------------
# RESTRAINT 10. THE SUM OF A GIVEN PARAMETER OF THE SPECIFIED ATOMS IS  
# RESTRAINED 
# ----------------------------------------------------------------------------

# This restraint, which will normally be used to restrain the total 
# occupancy of an atom site, can be used to restrain the value of
#   SUM(over the specified atoms){PARAMETER*COEFFICIENT} 
# where PARAMETER will usually be the occupancy 
# (but other allowed quantities such as x, y and z will be specified 
# in the enumeration list) and COEFFICIENT is a user defined 
# number with a default value of 1.0.
# The loop below describes the restraint, but it must be read in 
# conjunction with the class properties given in the second loop.
#


loop_        # category name restr_parameter
             # the first two items constitute the category key
_restr_parameter_class_id
_restr_parameter_atom_site_label
_restr_parameter_atom_coefficient
             # This multiplies the value of the parameter in the sum
             # It has a default value of 1.0
    # In Class 1 the sites O1, O1a and Olb refer to separate sites
    # over which oxygen is disordered, but in total they contain 0.8 oxygen atoms.
1 O1   1
1 O1a  1
1 O1b  1
    # Class 2 consists of a mixture of Na, K, Ca and Al atoms (on the same
    # site) with the total occupancy set to 1.0
2 Na1  1
2 K1   1
2 Ca1  1
2 Al1  1
    # Class 3 consists of the same atoms as Class 2, but by using coefficients
    # equal to the ionic charge, the total charge on the site is
    # restrained to 2.0. 
    # Note that the parameter restrained is still the occupancy
    # but the use of coefficients transforms the restraint from
    # occupancy to formal charge.
3 Na1  1
3 K1   1
3 Ca1  2
3 Al1  3
    # In Class 4 the y coordinate of O2 is restrained to be close to a 
    # pseudo-mirror plane at y = 0.5.  This example may not have much
    # practical use, but is included to show what can be done with this
    # definition.
4 O2   1
    # In Class 5 the positions of O3 and O4 are correlated in such a way that
    # these atoms are displaced equal distances from the plane x = 0 
    # (i.e., x(O3)+x(O4) = 0)
5 O3   1
5 O4   1


loop_        # category name is restr_parameter_class
_restr_parameter_class_class_id
             # category key, must be the same as 
             # _restr_paramter_class_id
_restr_parameter_class_parameter_type 
             # name of an allowed refinable parameter
_restr_parameter_class_target
             # target sum{coefficient*parameter}
_restr_parameter_class_target_weight_param
             # Expectation value of the difference between the target and the 
             # refined value of sum(coefficient*parameter)
_restr_parameter_class_details
             # description of the restraint applied
1 occupancy   0.8  0.01   'total occupation is 0.8'
2 occupancy   1.0  0.001  'total occupation is 1.0'
3 occupancy   2.0  0.01   'total charge is 2.0'
4 position_y  0.5  0.002  'keep close to pseudo-mirror plane'
5 position_x  0    0.01   'correlate position of O3 and O4'

#
#-------------------------------------------------------------------
# RESTRAINT 11: RIGID BODY
#-------------------------------------------------------------------

# New item in the atom_site category

_atom_site_rigid_body_id ?

# This may have any value.  All atoms having the same value of the id are 
# taken as belonging to the same rigid body.  This allows an unlimited number of 
# rigid bodies to be defined.  
# The target geometry will, because the body is rigid, be 
# the same as the refined geometry.  A program may refine the 
# center of mass and orientation of the rigid body, but these do not need to be 
# reported since they can be extracted, using a user-chosen coordinate system, from 
# the reported atomic coordinates.
# As this is a constraint, no weighting parameter is needed.


#-------------------------------------------------------------------
# RESTRAINT 12: GENERAL DESCRIPTION IF FURTHER RESTRAINTS
#-------------------------------------------------------------------

_restr_special_details

# A text field descibing any other restraints applied





