The Julia interface to chemfiles wrap around the C interface providing a Julian
API. All the functionalities are in the Chemfiles module, which can be imported
by the using Chemfiles expression. The Chemfiles module is built around the 5
main types of chemfiles: Trajectory, Frame, UnitCell, Topology, and
Atom.
Warning
All indexing in chemfiles is 0-based! That means that the first atom in a frame have the index 0, not 1. This is because no translation is made from the underlying C library.
This may change in future release to use 1-based indexing, which is more familiar to Julia developers.
These functions are not exported, and should be called by there fully qualified name:
Chemfiles.last_error()
Chemfiles.loglevel(Chemfiles.ERROR)
Chemfiles.last_error()¶Get the last error message.
Chemfiles.clear_errors()¶Clear the last error message.
Chemfiles.loglevel()¶Get the current log level.
Chemfiles.set_warning_callback(callback)¶Set the global warning callback to be used for each warning event.
The following logging levels are available:
Chemfiles.ERROR: Only log errors;Chemfiles.WARNING: Log warnings and erors. This is the default;Chemfiles.INFO: Log infos, warnings and errors;Chemfiles.DEBUG: Log everything.Chemfiles.logfile(file)¶Redirect the logs to file, overwriting the file if it exists.
Chemfiles.log_to_stdout()¶Redirect the logs to the standard output.
Chemfiles.log_to_stderr()¶Redirect the logs to the standard error output. This is enabled by default.
Chemfiles.log_silent()¶Remove all logging output
Chemfiles.log_callback(callback)¶Use a callback for logging, instead of the built-in logging system. The callback function will be called at each log event, with the event level and message.
The callback function must have the following signature:
function callback(level::Chemfiles.LogLevel, message::AbstractString)
# Do work as needed
return nothing
end
Trajectory type and associated functions¶A Trajectory uses a file and a format together to read simulation data from the file. It can read or write one or many Frame to this file. The file type and the format are automatically determined from the extention.
Trajectory(filename::String, mode::Char)¶Open a trajectory file.
| Parameters: |
|
|---|
read(trajectory::Trajectory) → Frame¶Read the next step of the Trajectory, and return the corresponding Frame.
read!(trajectory::Trajectory, frame::Frame)¶Read the next step of the Trajectory into an existing Frame.
read_step(trajectory::Trajectory, step) → Frame¶Read the given step of the Trajectory, and return the corresponding
Frame.
read_step(trajectory::Trajectory, step, frame::Frame)Read the given step of the Trajectory into an existing Frame.
write(trajectory::Trajectory, frame::Frame)¶Write a frame to the Trajectory.
set_topology!(trajectory::Trajectory, topology::Topology)¶Set the Topology associated with a Trajectory. This topology will be used when reading and writing the files, replacing any topology in the frames or files.
set_topology!(trajectory::Trajectory, filename:AbstractString)Set the Topology associated with a Trajectory by reading the first
frame of filename; and extracting the topology of this frame.
set_cell!(trajectory::Trajectory, cell::UnitCell)¶Set the UnitCell associated with a Trajectory. This cell will be used when reading and writing the files, replacing any unit cell in the frames or files.
nsteps(trajectory::Trajectory) → Integer¶Get the number of steps (the number of frames) in a Trajectory.
sync(trajectory::Trajectory)¶Synchronize any buffered content to the hard drive.
close(trajectory::Trajectory)¶Close a Trajectory, flushing any buffer content to the hard drive, and freeing the associated memory.
Frame type and associated functions¶A Frame holds data for one step of a simulation. As not all formats provides all the types of informations, some fields may be initialized to a default value. A Frame may contains the following data:
Frame(natoms = 0)¶Create an empty Frame with initial capacity of natoms. It will be
automatically resized if needed.
resize!(frame::Frame, natoms::Integer)¶Resize the positions and the velocities in Frame, to make space for natoms atoms. This function may invalidate any pointer to the positions or the velocities if the new size is bigger than the old one. In all the cases, previous data is conserved. This function conserve the presence or absence of velocities.
positions(frame::Frame) → Array{Float64, 2}¶Get a pointer to the positions in a Frame. The positions are readable and
writable from this array. If the frame is resized (by writing to it, or calling
resize), the array is invalidated.
velocities(frame::Frame)¶Get a pointer to the velocities in a Frame. The velocities are readable and
writable from this array. If the frame is resized (by writing to it, or calling
resize), the array is invalidated.
If the frame do not have velocity, this will return an error. Use
add_velocities! to add velocities to a frame before calling this function.
add_velocities!(frame::Frame)¶Add velocities to this Frame. The storage is initialized with the result of
size(frame) as number of atoms. If the frame already have velocities, this
does nothing.
add_atom!(frame::Frame, atom::Atom, position::Array{Float64}, velocity::Array{Float64})¶Add an atom and the corresponding position and velocity data to a frame. velocity can be NULL if no velocity is associated with the atom.
remove_atom!(frame::Frame, index::Integer)¶Remove the atom at index in the frame. This modify all the atoms indexes after index, and invalidate any pointer obtained using positions or velocities.
guess_topology!(frame::Frame)¶Guess the bonds, angles and dihedrals in the system using a distance criteria.
UnitCell type and associated function¶An UnitCell describe the bounding box of a system. It is represented by three base
vectors of lengthes a, b and c; and the angles between these vectors are
alpha, beta and gamma.
UnitCell(a, b, c, alpha=90, beta=90, gamma=90)¶Create an UnitCell from the three lenghts and the three angles.
UnitCell(frame::Frame)Get a copy of the UnitCell of a frame.
lengths(cell::UnitCell) -> (Float64, Float64, Float64)¶Get the three UnitCell lenghts (a, b and c) in angstroms.
angles(cell::UnitCell) -> (Float64, Float64, Float64)¶Get the three UnitCell angles (alpha, beta and gamma) in degrees.
set_angles!(cell::UnitCell, alpha, beta, gamma)¶Set the UnitCell angles to alpha, beta and gamma in degrees.
cell_matrix(cell::UnitCell) → Array{Float64, 2}¶Get the UnitCell matricial representation, i.e. the representation of the three base vectors as:
| a_x b_x c_x |
| 0 b_y c_y |
| 0 0 c_z |
The following cell types are defined:
Chemfiles.ORTHORHOMBIC : The three angles are 90°Chemfiles.TRICLINIC : The three angles may not be 90°Chemfiles.INFINITE : Cell type when there is no periodic boundary conditionsvolume(cell::UnitCell) → Float64¶Get the unit cell volume
Topology type and associated function¶A Topology describes the organisation of the particles in the system. What are there names, how are they bonded together, etc. A Topology is a list of Atom in the system, together with the list of bonds these atoms forms.
Topology(frame::Frame)Extract the Topology from a frame.
size(topology::Topology)Get the Topology size, i.e. the current number of atoms.
isbond(topology::Topology, i, j) → Bool¶Tell if the atoms i and j are bonded together.
isangle(topology::Topology, i, j, k) → Bool¶Tell if the atoms i, j and k constitues an angle.
isdihedral(topology::Topology, i, j, k, m) → Bool¶Tell if the atoms i, j, k and m constitues a dihedral angle.
nbonds(topology::Topology) → Integer¶Get the number of bonds in the system.
nangles(topology::Topology) → Integer¶Get the number of angles in the system.
ndihedrals(topology::Topology) → Integer¶Get the number of dihedral angles in the system.
bonds(topology::Topology) → Array{UInt, 2}¶Get the bonds in the system, arranged in a 2x nbonds array.
angles(topology::Topology) → Array{UInt, 2}Get the angles in the system, arranges as a 3x nangles array.
dihedrals(topology::Topology) → Array{UInt, 2}¶Get the dihedral angles in the system, arranged as a 4x ndihedrals array.
add_bond!(topology::Topology, i, j)¶Add a bond between the atoms i and j in the system.
remove_bond!(topology::Topology, i, j)¶Remove any existing bond between the atoms i and j in the system.
add_residue!(topology::Topology, residue::Residue)¶Add a copy of residue to this topology. The residue id must not already be in the topology, and the residue must contain only atoms that are not already in another residue.
count_residue(topology::Topology)¶Get the number of residues in the topology.
are_linked(topology::Topology, first::Residue, second::Residue)¶Check if the two residues first and second from the topology are linked together, i.e. if there is a bond between one atom in the first residue and one atom in the second one.
resize!(topology::Topology, natoms::Integer)Resize the topology to hold natoms atoms. If the new number of atoms is bigger than the current number, new atoms will be created with an empty name and type. If it is lower than the current number of atoms, the last atoms will be removed, together with the associated bonds, angles and dihedrals.
Atom type and associated function¶An Atom contains basic information about a single atom in the system: the name (if it is disponible), mass, type of atom and so on.
Atom(frame::Frame, idx::Integer)Get the Atom at index idx from the frame.
Atom(topology::Topology, idx::Integer)Get the Atom at index idx from the topology.
set_charge!(atom::Atom, charge::Number)¶Set the charge of an Atom to charge, in number of the electron charge e.
full_name(atom::Atom) → ASCIIString¶Try to get the full name of an Atom ("Helium") from the short name ("He").
vdw_radius(atom::Atom) → Float64¶Try to get the Van der Waals radius of an Atom from the short name. Returns -1 if no value could be found.
covalent_radius(atom::Atom) → Float64¶Try to get the covalent radius of an Atom from the short name. Returns -1 if no value could be found.
atomic_number(atom::Atom) → Integer¶Try to get the atomic number of an Atom from the short name. Returns -1 if no value could be found.
The following atom types are available:
Chemfiles.ELEMENT: Element from the periodic table of elementsChemfiles.COARSE_GRAINED: Coarse-grained atom are composed of more than one
element: CH3 groups, amino-acids are coarse-grained atoms.Chemfiles.DUMMY_ATOM: Dummy site, with no physical realityChemfiles.UNDEFINED_ATOM: Undefined atom typeResidue type and associated function¶Residue(name::String, resid::Integer)¶Create a new residue with the given name and residue identifier resid.
Residue(name::String)Create a new residue with the given name.
Residue(topology::Topology, index::Integer)Get a copy of the residue at index from a topology. If index is bigger than the result of count_residues, this function will return nothing. The residue index in the topology is not always the same as the residue id.
residue_for_atom(topology::Topology, index::Integer)¶Get a copy of the residue containing the atom at index in the topology. This function will return nothing if the atom is not in a residue, or if the index is bigger than natoms.
name(residue::Residue)Get the name of a residue.
id(residue::Residue)¶Get the identifier of a residue in the initial topology.
id(residue::Residue)Get the identifier of a residue in the initial topology.
size(residue::Residue)Get the number of atoms in a residue.
add_atom!(residue::Residue, i::Integer)Add the atom at index i in the residue.
contains!(residue::Residue, i::Integer)¶Check if the atom at index i is in the residue.
Selection type and associated function¶A Selection allow to select a group of atoms. Examples of selections are “name H” and “(x < 45 and name O) or name C”. See the full documentation for more information about the selection language.
size(selection::Selection) → IntegerGet the size of the Selection, i.e. the number of atoms we are selecting together.
evaluate(selection::Selection, frame::Frame) -> Array(Match, 1)¶Evaluate a Selection on a given Frame. This function return a list of indexes or tuples of indexes of atoms in the frame matching the selection.
selection_string(selection::Selection)¶Get the selection string used to create a given selection.