ICM Manual v.3.9
by Ruben Abagyan,Eugene Raush and Max Totrov
Copyright © 2020, Molsoft LLC
Jun 5 2024

Reference Guide
Command Line User's Guide
  mmff .
PrevICM Language Reference

[ iarray | integer | label | logical | macro | map | matrix | MIMEL | mmff . | mmcif | Mol | mol2 | more | trajectory | mute ]


A basic ICM class for arrays of integers: {5, 7, -100, 10}

See also: Iarray , Tointeger , read iarray.


numbers may exist in the ICM-shell as a named variable or a constant (e.g. 123,2,-45 ). There are several dozen predefined integer variables. Integers may be mentioned in arithmetic expressions, commands and functions.

 born =  1957 + 5              # she is 5 years younger  
 now  =  1996                  # lets pretend we live in 1996  
 if (now - born > 28) print "no, you are not 28, you are 27!" 


usually a string displayed in the ICM graphics window. Types of labels:

  • atom label # toggled by LeftMB clicking
  • residue label # toggled by LeftMB double clicking
  • variable label
  • free string label # drag it with the Middle mouse button.
To display the free text label, type:
display "Below lies a black abyss"
To delete it delete label i_labelNumber e.g. delete label 2
To show:
 show labels 


may exist in ICM-shell as a named variable or a constant (only two possibilities: yes and no ) You can use exclamation mark for negation ( !) and two operations: and ( & ) and or ( | ) There is a number of predefined logical variables. Logicals can be used in arithmetic expressions, most frequently in if ( logical ) ... expressions.
 l_nowIamDoingAStupidThing = yes & yes      
 l_Polite = no                     # another logical variable 
 if (Error & !l_Polite) print "And what do you think you are doing?" 


a group of ICM commands in a separate named function with arguments. Many advanced ICM tools are implemented as macros (e.g. icmPocketFinder. See description macro in the command section. See also user-defined (or icm-shell) functions which are the same as macros but may return a value and be nested.


a real function defined on a three-dimensional grid. Usually it is an electron density map or grid potential.

This ICM-shell object contains a descriptor (or header) with the following information:

  • cell type (space group number) and parameters {a, b, c, alpha, beta, gamma};
  • lattice and sublattice specifications (sizes and offsets for columns, rows and sections);
  • characteristics of the density values: the mean value, standard deviation, the minimum and the maximum values.
  • correspondence between X,Y,Z and sections, rows and columns
The map itself contains a stream of real density values for each node of the sublattice.
Maps can be read, calculated from structure factors, and created as a result of map arithmetics. Maps of 7 types (plus subtypes) of grid potentials can also be calculated with the make map potential command.

To create an empty map you may do the following:

build string "A" # just to some object in shell
make map potential name="x" !a_ {0. 0. 0. 10. 10. 10.}  1.  # a trick with empty cell and grid size 1.
for i=1,Nof(m,1)
 for j=1,Nof(m,2)
  for k=1,Nof(m,3)
    x[i,j,k]= Random(1.,3.)
x = Bracket( x Box(x) )  # a trick to update map stats

The make map potential The last map loaded or created becomes the current map. The current map is a convenient default for commands requiring map as an argument.
The following arithmetic operations between maps of compatible sizes are allowed: map+map, map+i, map+r, i+map, r+map map-map, map-i, map-r, i-map, r-map map*r, map*i, i*map, r*map, map*map map/r, map/i.
Map functions:
function description
Box( map )returns R_6box defining the map boundary
Bracket( ) same as Trim it also updates the map statistics, mean, stdev etc.
Cell( map )returns R_6 crystallographic cell parameters of the map
Index( m_EDS ) returns various index cell dimensions
make grob map r_sigma [name= s_name ] contour map
make grob g_contour add r_step re-contour map at new sigma level
converting x-ray map: make map potential map_Xray [as] [R_6box] [r_gridCellSize] [smooth] [name=s] to convert an oblique map into a fast rectangular map.
Map( map I_3_or_6 [ simple ] )a submap
Map( m_EDS cell ) returns a map in crystallographic cell
Index( m_EDS cell ) returns 3 xr-cell index dimensions
Min( map )minimal value
Max( map )maximal value
Nof( map )total number of grid points
Rarray( map )returns all values from 3D-grid points as a linear real array
Smooth( map [ expand] )space-average the map values
Symgroup( map )string with the symmetry group name
Trim( map, vMin vMax )trim by values outside the range
Trim( map, R_6box )set values outside the box to zero
Simple arithmetic operations are allowed with the maps (map1 and map2 must have the same dimensions):

  • plus (map1 + map2, map + r ),
  • minus (map1 - map2, map - r ),
  • multiply (map1 * map2, map*r, r*map ),
  • divide (map1 / map2, map/r ),
One can also use expressions, e.g.
 m = Smooth(m_ge)*2. - 1. + m_gc  # does not make much sense 

See also: icm.map


a set of real numbers organized in rows and columns. The ICM-shell allows arbitrary size matrices [n,m], access to its elements ( M[i,j] ), rows ( M[i] ), columns ( M[1:i,j] ) or any sub-matrix ( M[i1:i2,j1:j2] ). Basic matrix operations such as
  • plus (M1 + M2),
  • minus (M1 - M2),
  • multiply (M1 * M2),
  • concatenate rows ( M1 // M2 ),
  • equal ( M1 == M2 ),
  • not equal ( M1 != M2),
  • Transpose(M), and
  • inverse ( Power(M,-1) )
allow powerful matrix arithmetics. You can create a new matrix in the ICM-shell by

reading ( read matrix "a" ), assignment ( M_new=Transpose(M_old) ) or function Matrix ( e.g. M=Matrix(4,8)).

Appending an array as matrix row.This can be done with the add matrix [ M ] R command. If the matrix is not specified a new matrix will be created. E.g.

add matrix M {1. 2.} # creates new matrix M
add matrix M {3. 4.} # appends the second row to M

Making a matrix from table columns.The Matrix ( T S_columnNames ) returns a matrix with selected columns. E.g.

group table t {1. 2.} "A" {3. 3.} "B"
M = Matrix(t Name(t))  # returns a matrix

Converting a matrix into table columns The inverse operation of the previous Matrix function is the following: Table ( M [ S_columnNamesToBeCreated ] E.g.

T = Table(M {"AA","BB"})

Matrix-related functions are the following:

  • determinant of square matrix ( Det(M))
  • principal components or "distance geometry" ( Disgeo (M)) function, i.e. if a given square matrix M[1:n,1:n] contains distances between n points find coordinates in (n-1) dimensional space and sort the space dimensions according to their contribution to the variation. If distances are 3-dimensional Euclidean distances, the first three coordinates will give you x,y,z.
  • Eigen (M) function returns a matrix of eigenvectors; eigenvalues are stored in R_out
  • Distance( alignment) - returns matrix of pairwise distances between sequences in an alignment.
  • Max , Min , Mean and Sum functions return a row (actually a real array ) with maximal, minimal, mean, or total values in each column, respectively
  • Nof(M) and Length(M) - return n and m, respectively for matrix M[1:n,1:m] .
  • Power(M, i_exponent) calculates different integer powers of a matrix, including matrix inverse ( inmat=Power(M,-1)),
  • Random(d1,d2,n,m) creates a matrix and fills it with random numbers,
  • Rarray( M [1-7] ) returns matrix elements merged into an array. It can return merged rows (Rarray(M,1)), columns, upper and lower triangles with (3,4) or without (6,7) a diagonal; or only the diagonal (5).
  • Rmsd(M) returns root-mean-square deviation,
  • Trace(M) returns the trace of a square matrix,
  • Xyz( as_select) returns a matrix of xyz coordinates of selected atoms.
  • Distance( matrix) returns a matrix of pairwise distances between the row-vectors of the matrix.
Matrix assignments
 a=Matrix(4,5)           # create a matrix, simple assignment 
 a[1,1]=9.               # a single matrix element 
 a[2,?]={1. 2. 3. 4. 5.} # assign only the 2-nd row 
 a[?,3]={1. 2. 3. 4.}    # assign only the 3-nd column 
 a[2:3,1:2]=Random(-1.,1.,2,2) # assign only the 2x2 submatrix 
By simple arithmetic operations with matrices you can
  • solve a system of linear equations ( x=Power(A,-1)*B ),
  • find best set of parameters x[1:m] which fits your model A[1:n,1:m] (n > m) to data vector B[1:n]. Minimum of (A*x-B) is found by 3 steps:
     x =(M2*Transpose(A))*B 


an abbreviation of Modified IMage ELectrostatics algorithm ( Abagyan and Totrov, 1994) developed for fast evaluation of both internal Coulomb and electrostatic polarization free energy for large molecules. This term has no analytical derivatives and has no effect on local energy minimization. It can be a part of the energy function in global optimization such as montecarlo or ssearch . Three components of MIMEL can be shown using the show energy command. They are:
  • Coulomb interactions of explicit atomic charges (note that it is divided by the dielConst ICM-shell parameter)
  • "Self energy" (or interaction of explicit charges with their own images)
  • "Cross energy" (or interaction of explicit charges with other charges' images)
The last two components together represent the electrostatic polarization energy which is returned in the r_out variable. REBEL gives a more accurate evaluation of the electrostatic solvation. For small molecules use mimelDepth = 0.3. For proteins the error in the solvation energy evaluation (returned in the r_out variable) is estimated as 15 - 20%.

See also:

mmff .

This word refers to the Merck molecular force field described in a series of 1994 and 1999 publications by Thomas Halgren. ICM can assign MMFF atom types using local chemical environment, formal charges and 3D topology. ICM also allows one to calculate the mmff94 energy and minimize it both in the cartesian space with free covalent geometry and in the internal coordinate space with fixed covalent geometry or user-defined geometrical constraints.
See also:


A file with small molecule components of PDB can be found at the PDB ftp site. One entry from a components.cif file may looks like this:

_chem_comp.id         090
_chem_comp.name       "N-(2,3-DIHYDRO-7,8-DIMETHOXYIMIDAZO[1,2-C] QUINAZOLIN-5-Y.."
_chem_comp.type       NON-POLYMER
_chem_comp.pdbx_type  HETAIN
090 OAU  OAU  O 0 1 N N N 43.937 13.173 32.712 -3.244 -5.748  0.338  1
090 CAO  CAO  C 0 1 N N N 43.419 12.319 32.005 -4.133 -5.838  1.182  2
090 CAP  CAP  C 0 1 Y N N 42.044 11.803 32.337 -4.940 -7.065  1.305  3
090 CAQ  CAQ  C 0 1 Y N N 41.453 10.822 31.543 -6.233 -7.001  1.769  4
090 NAR  NAR  N 0 1 Y N N 40.245 10.336 31.880 -7.027 -8.087  1.907  5
090 CAX  CAX  C 0 1 Y N N 39.597 10.758 32.985 -6.484 -9.275  1.559  6
090 CAW  CAW  C 0 1 Y N N 40.149 11.706 33.832 -5.192 -9.428  1.083  7
090 CAV  CAV  C 0 1 Y N N 41.389 12.225 33.504 -4.406 -8.288  0.955  8
data_091  # THE NEXT ENTRY

The following commands will work on this kinds of files:

mol or sdf format

This word refers to the MDL Information Systems, Inc. SD-file format for small molecules (see trademarks). ICM can read and write molecules in this format. They may look like this:

jscorina  12209406473DS 
  7  6 
   -0.0187    1.5258    0.0104 C   0  0  0  0  0 
    0.0021   -0.0041    0.0020 C   0  0  0  0  0 
    1.6831    2.1537   -0.0024 S   0  0  0  0  0 
   -1.4333   -0.5336    0.0129 C   0  0  0  0  0 
    2.0692    1.9811   -1.7665 C   0  0  0  0  0 
   -1.4126   -2.0635    0.0045 C   0  0  0  0  0 
    1.4620    3.1542   -2.5386 C   0  0  0  0  0 
  2  1  1  0  0  0 
  3  1  1  0  0  0 
  4  2  1  0  0  0 
  5  3  1  0  0  0 
  6  4  1  0  0  0 
  7  5  1  0  0  0 
> <NSC> 
> <CAS_RN> 

A multiple-mol file (or sdf file) can contain also numeric or text fields that will be converted into real , integer or sarray columns (arrays) in a chemical table. The conversion routine supports special values and the ND INF >number fields will be interpreted as numbers as well.

See also:


This word refers to the Tripos file format for small molecules (see trademarks). ICM can read and write molecules in this format. The default extension for this type of file is .ml2. They may look like this:
     3     2 
     1  ho1    -2.0000    0.0000   -1.0000    H         1  hoh     0.3280 
     2  o      -2.4944    0.0000   -1.8229    O         1  hoh    -0.6550 
     3  ho2    -3.4149    0.0000   -1.5503    H         1  hoh     0.3280 
     1      1      2    1  
     2      2      3    1  
The ATOM record contains the following fields: atom_id atom_name x y z atom_type [ subst_id [ subst_name [ charge [ status_bit ] ] ] ]


an internal ICM-viewer for the output of ICM commands, a little brother of the UNIX browser. Displays ICM output one screenful at a time. Control:
  • spacebar: next page
  • Return: scroll by one line
  • /string: find string
  • n find next
  • q: quit

It is activated automatically under UNIX if the l_bufferedOutput parameter is set to yes .


a series of molecular conformations representing a Monte Carlo trajectory and saved in an ICM-formatted .trj binary file can be simply displayed or used for animated.
The icm .mov files are not quicktime movies, or series of images. Instead, they contain a compressed series of geometrical parameters determining object geometry for each accepted montecarlo iteration.
The frames of the trajectory file can be separately analyzed and further filtered with an ICM script. For example, one can generate a shorter trajectory file by retaining only the frames with lower energies.
See also: display trajectory, load frame


an option in a number of commands (e.g. find pattern, find prosite, show tether, show energy, show area, show volume, etc). It is usually used in scripts when one wants to suppresses unnecessary output. In macro declaration, this option suppresses prompting for missing macro arguments.


Copyright© 1989-2024, Molsoft,LLC - All Rights Reserved. Copyright© 1989-2024, Molsoft,LLC - All Rights Reserved. This document contains proprietary and confidential information of Molsoft, LLC. The content of this document may not be disclosed to third parties, copied or duplicated in any form, in whole or in part, without the prior written permission from Molsoft, LLC.