File Exchange

image thumbnail


version 2.07 (15.7 MB) by Michael Holmboe
Atomistic Topology Operations in MATLAB (atom), is a MATLAB library for manipulation of molecular systems


Updated 07 Feb 2020

View License

Atomistic Topology Operations in Matlab, scripts for manipulation of molecular dynamics or monte carlo simulation systems.

% Note that version 2.0x comes with an extensive html-documentation for all the >100 functions, which can be used interactively from Matlab's own browser.
% The purpose of the atom library is to automate and enable efficient construction/manipulation and analysis of complex and multicomponent molecular systems, and generate topological information with bonds and angles etc. It is especially useful for building inorganic/geochemical systems, since bond distances can be compared to the ideal semi-empirical bond distances computed with the Bond Valence Sum Method, or just simply just compared to Shannon's revised radii. Or one could plot a theoretical X-ray profile with the xrd_atom() function.

% For lists of all available functions by category, see inside these files:
% The atom scripts can read and write basic .pdb|.xyz|.gro|.mol2 structure files as well as write basic .itp and .psf topology files with bonds and angles across the PBC. The can also manipulate/transform the structures in various ways making use of the Matlab struct variable and indexing. The atom scripts can be used to build and plot multicomponent systems, by adding molecules, ions and SPC/TIP3P/TIP4P water molecules or other solvents (ie solvating an existing molecule/slab) into a simulation box, and remove molecular overlap. For plotting one can call vmd(atom,Box_dim) if the VMD software is also installed and the PATH2VMD() function is properly set. Else the very quick-and-dirty plot_atom(atom,Box_dim) or the slower show_atom(atom,Box_dim) can be used. Most functions takes PBC into account, which allows for generation of topologies of molecules with bonds, angles, dihedrals across the PBC. There is also some support for triclinic support using the tilt vectors xy, xz, yz, as well as for generating powder X-ray diffractograms using the function xrd_atom().
Michael Holmboe 
Chemistry department
Umeå University, Sweden
% Where to start? Perhaps the html-documentation with some basic examples? 

% Some typical commands...
% To read a structure file into matlab (check the variable explorer) 
atom=import_atom(filename) % filename could be a .pdb | .xyz | .gro file 
% or... 
% Note that you get a lot more info then just the atom struct variable, like the box dimension variable Box_dim 
% To write a atom struct to a new topology or structure file
write_atom_lmp(atom,Box_dim,filename,1.2,1.2,'clayff') % supports bonds, angles, simple dihedrals
write_atom_psf(atom,Box_dim,filename,1.2,1.2,'clayff') % note only bonds and angles
write_atom_itp(atom,Box_dim,filename,1.2,1.2,'clayff','spce') % Gromacs topology file, note only bonds and angles

% Adding water to a box 
% - This function SOLvates a certain region defined by limits with a water 
% structure with density. r (and r-0.5 for H) is the closest distance of solvent atoms
% to the (optional) solute atoms
SOL_atom = solvate_atom(limits,density,r,maxsol) % limits can be [10] | [10 20 30] | [10 20 30 40 50 60]
SOL_atom = solvate_atom(limits,density,r,maxsol,solute_atom,'tip4p') % spc | tip3p | tip4p | tip5p
% One can filter the atom struct with respect to molid, resname, atomtype, index, coordinates and so on. This allows manipulation of an atom struct on the atomic, molecule and molecular type level. This also allows us to use  'dynamic indexes' of groups of atom.{molid/resname/type/index/} when analyzing a trajectory for instance. Some basic examples: 
index=ismember([atom.type],[{'Al' 'Alt' 'Mgo'}]) % gives a binary (1/0) logical array 
index=strcmp([atom.type],'Al') % try also strncmp or strncmpi? 
index=find(strncmpi([atom.type],'al',2) % Will find the indexes of 'Al' 'Alt? 
new_atom=atom(index) % This creates a new_atom struct with the filtered/selected atomtypes 
positive_z_atom=atom([atom.z]>0) % finds all atoms with a positve z-coordinate
first100_atom=atom([atom.index]<101) % finds the first 100 atoms in the atom struct 
first100_v2_atom=atom(1:100) % also finds the first 100 atoms in the atom struct
% Merging two different atom structs 
% - This function returns the second atom set with non-overlapping atoms
new_atom = merge_atom(atom1,Box1,atom2,Box2,type,Atom_label,r)
% Calculating bonds or the distance matrix/es 
atom = bond_angle_dihedral_atom(atom,Box_dim,1.2,2.2)
dist_matrix = dist_matrix_atom(atom,Box_dim) % another cell lists version also exist.


Cite As

Holmboe, Michael. “Atom: A MATLAB PACKAGE FOR MANIPULATION OF MOLECULAR SYSTEMS.” Clays and Clay Minerals, Springer Science and Business Media LLC, Jan. 2020, doi:10.1007/s42860-019-00043-y.

View more styles

Comments and Ratings (6)

Awesome! I can't wait to have a try :D

Cheng zhong

Click on the Examples tab on this page to see all the functions. The Functions tab itself does not show them all for some reason..

Guomin Yang

It is really helpful to build system.



New bond_angle_dihedral_atom() function! A function that can find the indexes (see Dihedral_index) and calculate the dihedral angle between atoms that share two angles! Also some new features to the show_atom() plotting function.


Updates to the rdf_atom, density_atom and xrd_atom functions, plus a new very basic import_atom_mol2 function.


Various small updates, especially to the forcefield functions. Also, a new plotting function called show_atom(). Its a bit slow but puts on a good show! Try also the rewritten xrd_atom() function that can generate a simple X-ray profiles.


New cool density_atom function that can plot density profiles and if charges are present also can plot charge density profiles, electric field profiles and the electrostatic profile.


Small updates.


Moved from GitHub


Small updates.


New functions for healing/fusing/protonating sites, reading pdb trajectories with changing number of atoms etc.

Some small updates plus one new function called xrd_atom which generates a simplistic XRD pattern from a .pdb | .gro file or an existing atom struct with is Box_dim taken as the unit cell.

Some new functions and better support for triclinic systems.

Updated the documentation

Updated some documentation.

Mostly updates to some functions. Also added lists of all functions by category.

Improved documentation and some new LiveScripts demonstrating some of the atom struct functions. I have also added a small tutorial on how to use the scripts to construct a hydrated organoclay system.

Updated several functions, better supports trajectory import/export for instance. Try also the new solvate_atom function, solvates with spc, spce, tip3p, tip4p, tip5p water models at any given density.

Updated these files:
import_atom_gro.m, import_atom_xyz.m, import_gro_traj.m, import_traj.m, import_xyz_traj.m, write_atom_xyz.m, write_gro_traj.m, write_xyz_traj.m

Change of title.

Added more functions

Added more functions

Changed tags.

Added some more functions.

Added some functions for writing .psf and Gromacs .itp files

Added some more functions.

Update some plotting functions. If you want to use VMD, set your VMD path in PATH2VMD().

Added a picture!

Changed the description.

Changed the description again..

Changed title

Changed the description

Changed the description

Change description.

MATLAB Release Compatibility
Created with R2018a
Compatible with any release
Platform Compatibility
Windows macOS Linux

Inspired by: molecule3D

Inspired: Import and plot Gromacs .xvg data files