File Exchange

image thumbnail


version 2.04 (13.1 MB) by Michael Holmboe
Atomistic Topology Operations in Matlab, scripts for manipulation of molecular dynamics or monte carlo simulation systems


Updated 04 Jul 2019

View License

Atomistic Topology Operations in Matlab, scripts for manipulation of molecular dynamics or monte carlo simulation systems.
% The purpose of these atom scripts and functions 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. In the near future, I will also add scripts for trajectory analysis. 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.

% Version 2.0x comes with an extensive html documentation, which can be used interactively from Matlab's own browser.

% For lists of all available functions by category, see inside these files:
% The atom scripts can read and write basic .pdb .xyz and gromacs .gro 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 plot_density_atom(atom,Box_dim) functions which rapidly plots a full simulation box with thousands of atoms. Most functions, like dist_matrix_atom() and bond_angle_atom() takes PBC into account, which allows for generation of topologies of molecules with bonds across PBC. There is also some support for triclinic support using the tilt vectors xy, xz, yz.

% Any issues/concerns/bugs, email me. 
% Michael Holmboe 
% Chemistry department
% Umeå University 
% Sweden
% How to use? 

% To read a structure file into matlab (check the variable explorer) 
atom=import_atom(filename) % where filename is a .pdb | .xyz | .pdb 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_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
write_atom_cif(atom,Box_dim,filename) % Prints only fractional coordinates
% 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 us to manipulate an atom struct on % the atomic, molecule and molecular type level. This also allows us to use  'dynamic indexs' 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
% with a distance r away from the atoms in the first atom set
new_atom = merge_atom(atom1,Box1,atom2,Box2,type,Atom_label,r)
% Calculating a distance matrix/es 
% - This function calculates the distance matrix from the atom struct . Other versions using cell lists also exist.
dist_matrix = dist_matrix_atom(atom,Box_dim)
dist_matrix = dist_matrix_atom(atom1,atom2,Box_dim)

Cite As

Michael Holmboe (2019). atom (, MATLAB Central File Exchange. Retrieved .

Comments and Ratings (4)

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 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 R2017a
Compatible with any release
Platform Compatibility
Windows macOS Linux

Inspired: Import and plot Gromacs .xvg data files