Written by D. Svergun, C. Barberato, M. Malfios, V. Volkov, P. Konarev, M. Petoukhov, and A. Shkumatov.
Post all your questions about CRYSOL to the ATSAS Forum.

Manual

The following sections shortly describe the method implemented in CRYSOL, how to run CRYSOL from the command-line on any of the supported platforms, describe the dialog mode as well as the required input and the produced output files.

If you use results from CRYSOL in your own publication, please cite:
Svergun D.I., Barberato C. & Koch M.H.J. (1995) J. Appl. Cryst. 28, 768-773.

Introduction

CRYSOL is a program for evaluating the solution scattering from macromolecules with known atomic structure and possibly fitting it to experimental scattering curves from Small-Angle X-ray Scattering (SAXS). As an input one can either use a coordinate file in PDB or mmCIF file format, with an X-ray or NMR structure of a protein or a protein-DNA(RNA) complex. In addition, and contrary to previous versions, as of v3.1 CRYSOL also processes dummy atom and dummy residue models correctly.

The program uses multipole expansion of the scattering amplitudes to calculate the spherically averaged scattering pattern and takes into account different representations of the hydration shell. Given SAXS experimental data, CRYSOL can fit the theoretical scattering curve by minimizing the discrepancy (chi-square value) between the calculated scattering and the experimental data.

This fitting is done by varying three parameters: (i) average displaced solvent volume per atomic group (ii) contrast of the hydration shell (iii) relative background

To determine the number of implicit hydrogens, CRYSOL requires components.cif, the Chemical Component Dictionary maintained by the EBI. If not found, an error is reported:

error: ATSAS resource files not found. Check installation and ATSAS environment variable.

The file is part of the ATSAS package. Please check your installation.

Running crysol

Usage:

$> crysol [OPTIONS] [FILE(S)]

Here, FILE(S) are one or more atomic coordinate files to process, as well as experimental data to fit against. CRYSOL recognizes the following command-line arguments and options.

Command-Line Arguments and Options

Argument Description

FILE(S) At least one atomic coordinates file with extension .cif, .pdb or .ent, in either PDB or mmCIF format, and one or more optional experimental data files with extension .dat. The experimental data file format may be described as follows: The first line is always treated as a title. The following lines should contain momentum transfer, non-zero intensity and standard deviation, separated by whitespace.

Argument	Description
`FILE(S)`	At least one atomic coordinates file with extension `.cif`, `.pdb` or `.ent`, in either PDB or mmCIF format, and one or more optional experimental data files with extension `.dat`. The experimental data file format may be described as follows: The first line is always treated as a title. The following lines should contain momentum transfer, non-zero intensity and standard deviation, separated by whitespace.

Short Option	Long Option	Description
	`--model=<ID>`	Select a specific model ID from the coordinate file; default: all model IDs
	`--chain=<ID>`	Select a specific chain ID from the coordinate file; default: all chain IDs
	`--alternative-names`	Enable alternative (old) atom naming for all atomic structure files; default: disabled. See also: components.cif
	`--explicit-hydrogens`	Use explicit hydrogens provided in the atomic structure file; default: use implicit hydrogen groups determined by looking up the number of hydrogens in components.cif). See also option implicit-hydrogen.
	`--lm=<N>`	Maximum order of harmonics; default: 20, minimum: 1, maximum: 100. This defines the resolution of the calculated curve. The default value should be sufficient in most of the cases. For large or extended particles higher orders could improve the results, at the cost of an increased run time. This value must be increased whenever the maximum scattering angle is increased (smax).
	`--fb=<N>`	Order of Fibonacci grid; default: 17, minimum: 10, maximum: 18 The order of Fibonacci grid defines the number of points describing the surface of the macromolecule. Higher grid orders give a more accurate surface representation, but more CPU expensive. Only used if option `shell=directional` (the default).
	`--ns=<N>`	Number of calculated data points; default: 101, maximum = 10001.
	`--smax=<SM>`	Maximum scattering angle in inverse angstroms, either for calculating the theoretical curve up to sm or for fitting till sm; default: 0.5Å^-1, maximum: 2.0Å^-1
	`--units<N>`	Angular units of the experimental data: 1 = 1/Å, s = 4πsin(θ)/λ 2 = 1/nm, s = 4πsin(θ)/λ 3 = 1/Å, s = 2sin(θ)/λ 4 = 1/nm, s = 2sin(θ)/λ By default, an attempt is made to estimate the unit scale.
	`--dns<VALUE>`	Solvent density; default: 0.334 e/Å³, the electron density of pure water. Solvents with high salt concentration may have a somewhat higher electron density. User can adjust the value accordingly.
	`--dro<VALUE>`	Contrast of hydration shell, default: 0.03 e/Å³
	`--constant`	Enables constant subtraction. This operation accounts for possible systematic errors due to mismatched buffers in the experimental data.
	`--skip-minimization`	Skip adjustment of parameters and calculate fit to experimental data with dns/dro values provided
	`--energy=<eV>`	X-ray energy in eV, required for energy correction in anomalous SAXS only.
	`--shell=<VALUE>`	Shell kind, one of 'directional' (classic CRYSOL) or 'water' (previously CRYSOL3)
`-p`	`--prefix=<FILE>`	The PREFIX to prepend to any output filename; default: basename of the input file(s).
	`--implicit-hydrogen=<N>`	Set this to a value N>=0 to override 'unable to determine number of hydrogens' errors.
	`--sub-element==<NAME>`	Set this to a valid element to override 'unable to determine element' errors.
`-o`	`--version`	Print version information and exit.
`-h`	`--help`	Print this help text and exit.

Mandatory arguments to long options are mandatory for short options too.

Runtime Output

On runtime, a number of parameters will be reported for each input model. These are also recorded in the .log output file.

crysol Input Files

CRYSOL reads one or more atomic coordinates file in either PDB or mmCIF format.

Optionally zero, one or more experimental data sets can be supplied. See the FILE-argument.

crysol Output Files

All output files start with prefix and appended suffix.

If no prefix is provided, output file names are generated based on the base name of the inputs. For example: "6lyz.cif" generates 6lyz.log, 6lyz.int, 6lyz.abs and "6lyz.cif lyzexp.dat" creates 6lyz_lyzexp.log and 6lyz_lyzexp.fit in addition. With prefix, the two .log files are merged into one.

Suffix	Type	Description
`.log`	ASCII	Contains the screen output and the detailed warning messages.
`.int`	ASCII	The first line is a title. Five columns contain: (1) experimental scattering vector in inverse angstroms, (2) theoretical intensity in solution, (3) in vacuo, (4) the solvent scattering and (5) the border layer scattering.
`.abs`	ASCII	The first line is a title. Contains two columns: (1) scattering vector in inverse angstroms, (2) theoretical intensity in absolute scale I_abs(s)[cm^-1]/c[mg/ml]
`.fit`	ASCII	Contains the fit to the experimental data in inverse angstroms.
`.alm`	BINARY	Sum of the scattering amplitudes for atoms, excluded volume and border. It can be used for rigid body modelling with MASSHA, SASREF and BUNCH later.

The header of the .fit file contains the following fields:

Field	Description
`Dro`	Optimal hydration shell contrast.
`Ra`	Optimal atomic group radius (in Å).
`RGT`	Radius of gyration (in Å) estimated from the theoretical curve.
`Vol`	Optimal excluded volume (in Å³).
`Chi^2`	Discrepancy between theoretical and experimental curves.

Examples

All examples use 6lyz.pdb, lyz_014.dat and lyzexp.dat. They are included in the documentation directory of the installation package

Calculating scattering intensity without fitting

$ crysol 6lyz.pdb --lm 18

Use CRYSOL to calculate the scattering intensity from the PDB file. Maximum order of harmonics = 18

Processing of PDB file with fitting.

$ crysol 6lyz.pdb *.dat --constant

Use CRYSOL to calculate the scattering intensity from the PDB file, fit to all available experimental data, use constant subtraction to improve fit.

Processing multiple PDB files with fitting.

$ crysol 4mld.pdb SASDAB7_fit1_model1.pdb SASDAB7.dat

Use CRYSOL to calculate the fit of the SASDAB7 scattering curve against the ComE protein alone (4mld.pdb) and in complex with its DNA promoter region (SASDAB7_fit1_model1.pdb).

$ crysol 1f6g.pdb exp_file.dat --model 5 --chain A

Use CRYSOL to process chain A of conformer #5 from NMR ensemble (1f6g.pdb) and fit to experimental data

Table of Contents