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 main types of chemfiles: Trajectory, Frame, UnitCell,
Topology, Residue, Atom, and Selection.
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.set_warning_callback(my_callback)
last_error
()¶clear_errors
()¶set_warning_callback
(callback::Function)¶Set the global warning callback
to be used for each warning event.
The callback
function must take a String
and return nothing.
add_configuration
(path)¶Read configuration data from the file at path.
By default, chemfiles reads configuration from any file name .chemfilesrc in the current directory or any parent directory. This function can be used to add data from another configuration file.
This function will fail if there is no file at path, or if the file is incorectly formatted. Data from the new configuration file will overwrite any existing data.
version
()¶Trajectory
type and associated functions¶Trajectory
¶A Trajectory
represents a simulation file on the hard drive. It can read
or write one or many Frame
to this file. The file format can be
automatically determined from the extention, or manually specified.
Trajectory
(ptr::Ptr{lib.CHFL_TRAJECTORY})¶Trajectory
represents a simulation file on the hard drive. It can read
or write one or many Frame
to this file. The file format can be
automatically determined from the extention, or manually specified.Trajectory
(path::AbstractString, mode::Char = r, format::AbstractString = "")¶Trajectory
function open a trajectory file, using the file at the given
path
. The opening mode
can be 'r'
for read, 'w'
for write or
'a'
for append, and defaults to 'r'
. The optional format
parameter
give a specific file format to use when opening the file.read
(trajectory::Trajectory)¶trajectory
, and return the corresponding Frame
.read!
(trajectory::Trajectory, frame::Frame)¶trajectory
in the given frame
.read_step
(trajectory::Trajectory, step::Integer)¶step
of the trajectory
, and return the corresponding
Frame
.read_step!
(trajectory::Trajectory, step::Integer, frame::Frame)¶step
of the trajectory
in the given frame
.write
(trajectory::Trajectory, frame::Frame)¶frame
to the trajectory
.set_topology!
(trajectory::Trajectory, topology::Topology)¶Topology
associated with a trajectory
. This topology will be
used when reading and writing the files, replacing any topology in the file.set_topology!
(trajectory::Trajectory, path::AbstractString, format::AbstractString = "")¶Topology
associated with a trajectory
by reading the first frame
of the file at path
; and extracting the topology of this frame. The optional
format
parameter can be used to specify the file format.set_cell!
(trajectory::Trajectory, cell::UnitCell)¶cell
associated with a trajectory
. This cell will be used when
reading and writing the files, replacing any unit cell in the file.nsteps
(trajectory::Trajectory)¶trajectory
.close
(trajectory::Trajectory)¶trajectory
, flushing any buffer content to the hard drive, and
freeing the associated memory.isopen
(trajectory::Trajectory)¶trajectory
is openFrame
type and associated functions¶Frame
¶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:
Topology
of the system;UnitCell
of the system.Frame
(ptr::Ptr{lib.CHFL_FRAME})¶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:
Topology
of the system;UnitCell
of the system.Frame
()¶Frame
.deepcopy
(frame::Frame)¶frame
.size
(frame::Frame)¶frame
size, i.e. the current number of atoms.resize!
(frame::Frame, natoms::Integer)¶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)¶Frame
as an array. 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 the velocities in a Frame
as an array. 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 function will error. You can use
add_velocities!
to add velocities to a frame before calling this function.
add_velocities!
(frame::Frame)¶frame
. The storage is initialized with the result of
size(frame)
as number of atoms. If the frame already have velocities, this
does nothing.has_velocities
(frame::Frame)¶frame
contains velocity data or not.add_atom!
(frame::Frame, atom::Atom, position::Vector{Float64}, velocity::Vector{Float64} = Float64[0.0, 0.0, 0.0])¶atom
and the corresponding position
and velocity
data to a
frame
.remove_atom!
(frame::Frame, index::Integer)¶Remove the atom
at index
from the frame
.
This modify all the atoms
indexes after index
, and invalidate any
array obtained using positions
or velocities
.
set_cell!
(frame::Frame, cell::UnitCell)¶cell
associated with a frame
.set_topology!
(frame::Frame, topology::Topology)¶topology
associated with a frame
.step
(frame::Frame)¶frame
step, i.e. the frame number in the trajectory.set_step!
(frame::Frame, step::Integer)¶frame
step to step
.guess_bonds!
(frame::Frame)¶frame
using a distance criteria.add_bond!
(frame::Frame, i::Integer, j::Integer)¶Frames
’s Topology
.remove_bond!
(frame::Frame, i::Integer, j::Integer)¶Frames
’s Topology
.add_residue!
(frame::Frame, residue::Residue)¶Frames
’s Topology
.distance
(frame::Frame, i::Integer, j::Integer)¶angle
(frame::Frame, i::Integer, j::Integer, k::Integer)¶dihedral
(frame::Frame, i::Integer, j::Integer, k::Integer, m::Integer)¶out_of_plane
(frame::Frame, i::Integer, j::Integer, k::Integer, m::Integer)¶property
(frame::Frame, name::String)¶set_property!
(frame::Frame, name::String, property)¶Frame
.UnitCell
type and associated function¶UnitCell
¶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
(ptr::Ptr{lib.CHFL_CELL})¶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::Number, b::Number, c::Number)¶UnitCell
from the three lenghts, with all the angles equal to 90°.UnitCell
(a::Number, b::Number, c::Number, α::Number, β::Number, γ::Number)¶UnitCell
from the three lenghts and three angles.UnitCell
(frame::Frame)¶UnitCell
of a frame
.deepcopy
(cell::UnitCell)¶cell
.volume
(cell::UnitCell)¶cell
volumelengths
(cell::UnitCell)¶cell
lenghts (a, b and c) in angstroms.set_lengths!
(cell::UnitCell, a::Real, b::Real, c::Real)¶Set the cell
lenghts to a
, b
and c
.
a
, b
and c
should be in angstroms.
angles
(cell::UnitCell)¶cell
angles (alpha, beta and gamma) in degrees.set_angles!
(cell::UnitCell, α::Real, β::Real, γ::Real)¶Set the cell angles to α
, β
and γ
.
α
, β
and γ
should be in degrees.
cell_matrix
(cell::UnitCell)¶Get the cell
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 |
shape
(cell::UnitCell)¶cell
shape, as a CellShape
valueset_shape!
(cell::UnitCell, shape::CellShape)¶cell
shape to the given shape
.CellShape
¶The possible shape for an unit cell are:
Chemfiles.ORTHORHOMBIC
for unit cell with the three angles are 90°Chemfiles.TRICLINIC
for unit cell where the three angles may not be 90°Chemfiles.INFINITE
for unit cells without boundariesCellShape
(value)¶The possible shape for an unit cell are:
Chemfiles.ORTHORHOMBIC
for unit cell with the three angles are 90°Chemfiles.TRICLINIC
for unit cell where the three angles may not be 90°Chemfiles.INFINITE
for unit cells without boundariesTopology
type and associated function¶Topology
¶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 between
the atoms.
Topology
(ptr::Ptr{lib.CHFL_TOPOLOGY})¶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 between
the atoms.Topology
()¶Topology
.Topology
(frame::Frame)¶Topology
of the given frame
.deepcopy
(topology::Topology)¶topology
.size
(topology::Topology)¶Topology
size, i.e. the current number of atoms.add_atom!
(topology::Topology, atom::Atom)¶atom
at the end of a topology
.remove!
(topology::Topology, index::Integer)¶index
from a topology
.bonds_count
(topology::Topology)¶topology
.angles_count
(topology::Topology)¶topology
.dihedrals_count
(topology::Topology)¶topology
.impropers_count
(topology::Topology)¶topology
.bonds
(topology::Topology)¶topology
, in a 2 x bonds_count(topology)
array.angles
(topology::Topology)¶topology
, in a 3 x angles_count(topology)
array.dihedrals
(topology::Topology)¶topology
, in a 4 x dihedrals_count(topology)
array.impropers
(topology::Topology)¶topology
, in a 4 x impropers_count(topology)
array.add_bond!
(topology::Topology, i::Integer, j::Integer)¶i
and j
in the topology
.remove_bond!
(topology::Topology, i::Integer, j::Integer)¶i
and j
in the topology
.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_residues
(topology::Topology)¶topology
.are_linked
(topology::Topology, first::Residue, second::Residue)¶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, size::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¶Atom
¶An Atom
is a particle in the current Frame
.
The atom name is usually an unique identifier (“H1”, “C_a”) while the atom type will be shared between all particles of the same type: “H”, “Ow”, “CH3”.
Atom
(ptr::Ptr{lib.CHFL_ATOM})¶An Atom
is a particle in the current Frame
.
The atom name is usually an unique identifier (“H1”, “C_a”) while the atom type will be shared between all particles of the same type: “H”, “Ow”, “CH3”.
Atom
(name::String)¶name
and set the atom type
to be the same
as name
.Atom
(frame::Frame, index::Integer)¶atom
at the given index
from a frame
Atom
(topology::Topology, index::Integer)¶atom
at a given index
from a topology
deepcopy
(atom::Atom)¶atom
.mass
(atom::Atom)¶Get the mass of an atom
.
The mass is given in atomic mass units.
set_mass!
(atom::Atom, mass)¶Set the mass of an atom
to mass
.
The mass must be in atomic mass units.
charge
(atom::Atom)¶Get the charge of an atom
.
The charge is in number of the electron charge e.
set_charge!
(atom::Atom, charge)¶Set the charge of an atom
to charge
.
The charge must be in number of the electron charge e.
name
(atom::Atom)¶atom
set_name!
(atom::Atom, name::String)¶atom
to name
.fullname
(atom::Atom)¶Get the full name of an atom
from the atom type.
For example, the full name of an atom with type “He” is “Helium”.
vdw_radius
(atom::Atom)¶Get the Van der Waals radius of an atom
from the atom type.
If the radius can not be found, this function returns -1.
covalent_radius
(atom::Atom)¶Get the covalent radius of an atom
from the atom type.
If the radius can not be found, returns -1.
atomic_number
(atom::Atom)¶Get the atomic number of an atom
from the atom type.
If the atomic number can not be found, returns 0.
atom_type
(atom::Atom)¶atom
.set_atom_type!
(atom::Atom, atom_type::String)¶atom
to type
.property
(atom::Atom, name::String)¶set_property!
(atom::Atom, name::String, property)¶Residue
type and associated function¶Residue
¶A Residue
is a group of atoms belonging to the same logical unit. They
can be small molecules, amino-acids in a protein, monomers in polymers,
etc.
Residue
(ptr::Ptr{lib.CHFL_RESIDUE})¶Residue
is a group of atoms belonging to the same logical unit. They
can be small molecules, amino-acids in a protein, monomers in polymers,
etc.Residue
(name::String)¶name
Residue
(name::String, resid::Integer)¶name
and residue identifier resid
.Residue
(topology::Topology, index::Integer)¶Get a copy of the residue at index
from a topology
.
The residue index in the topology is not always the same as the residue identifier.
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 the number of atoms in the topology.
deepcopy
(residue::Residue)¶residue
.name
(residue::Residue)¶residue
.id
(residue::Residue)¶residue
in the initial topology.size
(residue::Residue)¶residue
.add_atom!
(residue::Residue, index::Integer)¶index
in the residue
.contains
(residue::Residue, index::Integer)¶index
is in the residue
.deepcopy
(residue::Residue)¶residue
.Selection
type and associated function¶Selection
¶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.
Selection
(ptr::Ptr{lib.CHFL_SELECTION})¶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.Selection
(selection::AbstractString)¶Selection
from a selection stringdeepcopy
(selection::Selection)¶selection
.size
(selection::Selection)¶selection
, i.e. the number of atoms we are selecting
together.evaluate
(selection::Selection, frame::Frame)¶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)¶selection
.