TLSANL (CCP4: Supported Program)


tlsanl - analysis of TLS tensors and derived anisotropic U factors


tlsanl xyzin input.brk tlsin input.tls xyzout output.brk [ axes ]
[Keyworded input]


The program analyses TLS tensors and is intended for use with the output of RESTRAIN or REFMAC.



An ASCII file containing details of the TLS groups and the values of the corresponding T, L and S tensors. See the
RESTRAIN documentation for details of the file format. In addition to the records described there, the file may contain a line "REFMAC" denoting that the file has been output from the refinement program REFMAC, which has a different order of tensor elements.


Input coordinates in PDB format. ANISOU records are ignored. ATOM records may contain the full B factor (as output by RESTRAIN) or only the residual B factor (which doesn't include the contribution from the TLS parameters, as output by REFMAC). The program interprets the B factors according to the keyword BRESID.


Output coordinates and anisotropic tensors in PDB format. The ATOM records may contain the full B factor, the residual B factor, or the TLS-component of the B factor according to the keyword ISOOUT. The ANISOU records contain the full anisotropic displacement parameters, irrespective of the ISOOUT keyword.


Output file containing the axes for translation, libration, screw-rotation, reduced translation and non-intersecting screw-rotation. The file is in a suitable format for including in a MOLSCRIPT .in file. See AXES keyword below.


Available keywords are:



Do anisotropic tensor analysis (default: don't). The principal axes of the anisotropic tensor are determined for each atom in each TLS group and written to the log output. If the tensor is non-positive definite, then a warning is given. The anisotropic tensor includes the isotropic contribution as well as the contribution from the TLS parameters.

BINPUT [true | t | false | f]

If true (default), assume PDB file contains isotropic B factors. Else, assume PDB file contains isotropic U factors (smaller by 8*pi**2).

BRESID [true | t | false | f]

If true, assume the ATOM records in XYZIN contain only residual B factors, and don't include the contribution from the TLS parameters. If false (default), assume the ATOM records contain the full B factor, including the contribution from TLS.


Determine whether the ATOM records in XYZOUT contain B factors calculated from the TLS parameters (TLSC), residual B factors (RESI), or the sum of both (FULL). Default is FULL.

AXES [ < scale > ]

A file (logical name AXES) is output containing the axes for translation, libration, screw-rotation, reduced translation and non-intersecting screw-rotation, for each TLS group. All axes are calculated in an orthogonal frame with respect to the centre of reaction. The file is in a suitable format for including in a MOLSCRIPT .in file.

Each axis is written as a pair of coordinates (in the coordinate system of the input PDB file) representing the beginning and the end of the axis. For the intersecting axes, the intersection is at the centre of reaction of the TLS group. The length of each axis is proportional to the magnitude of the corresponding motion. The proportionality factor can be adjusted by the argument < scale >, which defaults to 10.


Terminate input.


For each TLS group included in the file TLSIN, the program outputs information about the TLS tensors in several representations. Two coordinate origins are considered:
  1. The origin used in refinement, and given by the ORIGIN record in TLSIN.
  2. The centre of reaction, which is the origin that makes S symmetric. TLS tensors with respect to this origin are flagged with a prime (').
Three axial systems are considered:
  1. Orthogonal axes, as used in XYZIN and TLSIN
  2. Libration axes, i.e. the principal axes of the L tensor. TLS tensors in this axial system are flagged with a caret (^).
  3. Rigid-body axes.
The values of the T, L and S tensors are given with respect to both origins, and in the first two axial systems. The L tensor is in general independent of the origin, and in particular is the same for both origins considered here. In the axial system defined by the libration axes only, the diagonal elements of S are also independent of origin.

The values of the T and S tensors held in TLSIN thus depend on the origin chosen for their calculation. The Centre of Reaction, however, is independent of the original origin, and hence so are quantities calculated with respect to the Centre of Reaction.

The rigid body motion can also be described as 3 screw motions about 3 non-intersecting axes parallel to the libration axes, together with a reduced translation tensor (see Schomaker and Trueblood (1968)). The program gives the absolute position of these screw axes and the pitch of the screw motion along them, followed by the reduced translation tensor.


For files generated by RESTRAIN, defaults can be accepted, although the ANISO keyword might be useful:

tlsanl XYZIN foo_in.pdb TLSIN foo_in.tls XYZOUT foo_out.pdb <<eof

For files generated by REFMAC, the BRESID keyword will be needed:

tlsanl XYZIN foo_in.pdb TLSIN foo_in.tls XYZOUT foo_out.pdb <<eof


  1. B.Howlin, S.A.Butler, D.S.Moss, G.W.Harris and H.P.C.Driessen, "TLSANL: TLS parameter analysis program for segmented anisotropic refinement of macromolecular structures.", J. Appl. Cryst., 26, 622-624 (1993)
  2. V.Schomaker and K.N.Trueblood Acta Cryst., B24, 63 (1968)


restrain, refmac


Huub Driessen, David Moss, Ian Tickle et al., Birkbeck College.

Contact: Ian Tickle (, Martyn Winn (