Julia interface reference¶

Miscelaneous functions¶

These functions are not exported, and should be called by there fully qualified name:

Chemfiles.last_error()
Chemfiles.set_warning_callback(my_callback)

function last_error()¶

Get the last error message from the chemfiles runtime.

function clear_errors()¶

Clear any error message stored by the chemfiles runtime.

function 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.

function 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.

function version()¶

Trajectory type and associated functions¶

type 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.

function Trajectory(ptr::Ptr{lib.CHFL_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.

function Trajectory(path::AbstractString, mode::Char = r, format::AbstractString = "")¶

The 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.

function read(trajectory::Trajectory)¶

Read the next step of the trajectory, and return the corresponding Frame.

function read!(trajectory::Trajectory, frame::Frame)¶

Read the next step of the trajectory in the given frame.

function read_step(trajectory::Trajectory, step::Integer)¶

Read the given step of the trajectory, and return the corresponding Frame.

function read_step!(trajectory::Trajectory, step::Integer, frame::Frame)¶

Read the given step of the trajectory in the given frame.

function write(trajectory::Trajectory, frame::Frame)¶

Write the given frame to the trajectory.

function 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 file.

function set_topology!(trajectory::Trajectory, path::AbstractString, format::AbstractString = "")¶

Set the 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.

function set_cell!(trajectory::Trajectory, cell::UnitCell)¶

Set the cell associated with a trajectory. This cell will be used when reading and writing the files, replacing any unit cell in the file.

function nsteps(trajectory::Trajectory)¶

Get the number of steps (the number of frames) in a trajectory.

function close(trajectory::Trajectory)¶

Close a trajectory, flushing any buffer content to the hard drive, and freeing the associated memory.

function isopen(trajectory::Trajectory)¶

Check is the trajectory is open

Frame type and associated functions¶

type 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:

• Positions for all the atoms in the system;
• Velocities for all the atoms in the system;
• The Topology of the system;
• The UnitCell of the system.

function 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:

• Positions for all the atoms in the system;
• Velocities for all the atoms in the system;
• The Topology of the system;
• The UnitCell of the system.

function Frame()¶

Create a new empty Frame.

function deepcopy(frame::Frame)¶

Make a deep copy of a frame.

function size(frame::Frame)¶

Get the frame size, i.e. the current number of atoms.

function resize!(frame::Frame, natoms::Integer)¶

Resize the positions and the velocities in a 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.

function positions(frame::Frame)¶

Get the positions in a 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.

function 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.

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.

function has_velocities(frame::Frame)¶

Check if a frame contains velocity data or not.

function add_atom!(frame::Frame, atom::Atom, position::Vector{Float64}, velocity::Vector{Float64} = Float64[0.0, 0.0, 0.0])¶

Add an atom and the corresponding position and velocity data to a frame.

function 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.

function set_cell!(frame::Frame, cell::UnitCell)¶

Set the cell associated with a frame.

function set_topology!(frame::Frame, topology::Topology)¶

Set the topology associated with a frame.

function step(frame::Frame)¶

Get the frame step, i.e. the frame number in the trajectory.

function set_step!(frame::Frame, step::Integer)¶

Set the frame step to step.

function guess_bonds!(frame::Frame)¶

Guess the bonds, angles and dihedrals in the frame using a distance criteria.

function add_bond!(frame::Frame, i::Integer, j::Integer)¶

Add an additional bond to the Frames’s Topology.

function remove_bond!(frame::Frame, i::Integer, j::Integer)¶

Remove a bond from the Frames’s Topology.

function add_residue!(frame::Frame, residue::Residue)¶

Add a residue to the Frames’s Topology.

function distance(frame::Frame, i::Integer, j::Integer)¶

Calculate the distance between two atoms.

function angle(frame::Frame, i::Integer, j::Integer, k::Integer)¶

Calculate the angle made by three atoms.

function dihedral(frame::Frame, i::Integer, j::Integer, k::Integer, m::Integer)¶

Calculate the dihedral (torsional) angle made by four unbranched atoms.

function out_of_plane(frame::Frame, i::Integer, j::Integer, k::Integer, m::Integer)¶

Calculate the out-of-plane (improper) angle made by four atoms.

function property(frame::Frame, name::String)¶

Get a named property for the given atom.

function set_property!(frame::Frame, name::String, property)¶

Set a named property for the given Frame.

UnitCell type and associated function¶

type 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.

function UnitCell(ptr::Ptr{lib.CHFL_CELL})¶

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.

function UnitCell(a::Number, b::Number, c::Number)¶

Create an UnitCell from the three lenghts, with all the angles equal to 90°.

function UnitCell(a::Number, b::Number, c::Number, α::Number, β::Number, γ::Number)¶

Create an UnitCell from the three lenghts and three angles.

function UnitCell(frame::Frame)¶

Get a copy of the UnitCell of a frame.

function deepcopy(cell::UnitCell)¶

Make a deep copy of a cell.

function volume(cell::UnitCell)¶

Get the unit cell volume

function lengths(cell::UnitCell)¶

Get the three cell lenghts (a, b and c) in angstroms.

function 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.

function angles(cell::UnitCell)¶

Get the three cell angles (alpha, beta and gamma) in degrees.

function set_angles!(cell::UnitCell, α::Real, β::Real, γ::Real)¶

Set the cell angles to α, β and γ.

α, β and γ should be in degrees.

function 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 |

function shape(cell::UnitCell)¶

Get the cell shape, as a CellShape value

function set_shape!(cell::UnitCell, shape::CellShape)¶

Set the cell shape to the given shape.

type 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 boundaries

function CellShape(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 boundaries

Topology type and associated function¶

type 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.

function Topology(ptr::Ptr{lib.CHFL_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.

function Topology()¶

Create an empty Topology.

function Topology(frame::Frame)¶

Get a copy of the Topology of the given frame.

function deepcopy(topology::Topology)¶

Make a deep copy of a topology.

function size(topology::Topology)¶

Get the Topology size, i.e. the current number of atoms.

function add_atom!(topology::Topology, atom::Atom)¶

Add an atom at the end of a topology.

function remove!(topology::Topology, index::Integer)¶

Remove the atom at the given index from a topology.

function bonds_count(topology::Topology)¶

Get the number of bonds in the topology.

function angles_count(topology::Topology)¶

Get the number of angles in the topology.

function dihedrals_count(topology::Topology)¶

Get the number of dihedral angles in the topology.

function impropers_count(topology::Topology)¶

Get the number of improper angles in the topology.

function bonds(topology::Topology)¶

Get the bonds in the topology, in a 2 x bonds_count(topology) array.

function angles(topology::Topology)¶

Get the angles in the topology, in a 3 x angles_count(topology) array.

function dihedrals(topology::Topology)¶

Get the dihedral angles in the topology, in a 4 x dihedrals_count(topology) array.

function impropers(topology::Topology)¶

Get the improper angles in the topology, in a 4 x impropers_count(topology) array.

function add_bond!(topology::Topology, i::Integer, j::Integer)¶

Add a bond between the atoms i and j in the topology.

function remove_bond!(topology::Topology, i::Integer, j::Integer)¶

Remove any existing bond between the atoms i and j in the topology.

function 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.

function count_residues(topology::Topology)¶

Get the number of residues in the topology.

function 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.

function 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¶

type Atom¶

An Atom is a particle in the current Frame.

An atom stores the following atomic properties:

• atom name
• atom type
• atom mass
• atom charge

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”.

function Atom(ptr::Ptr{lib.CHFL_ATOM})¶

An Atom is a particle in the current Frame.

An atom stores the following atomic properties:

• atom name
• atom type
• atom mass
• atom charge

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”.

function Atom(name::String)¶

Create an atom with the given name and set the atom type to be the same as name.

function Atom(frame::Frame, index::Integer)¶

Get a copy of the atom at the given index from a frame

function Atom(topology::Topology, index::Integer)¶

Get a copy of the atom at a given index from a topology

function deepcopy(atom::Atom)¶

Make a deep copy of an atom.

function mass(atom::Atom)¶

Get the mass of an atom.

The mass is given in atomic mass units.

function set_mass!(atom::Atom, mass)¶

Set the mass of an atom to mass.

The mass must be in atomic mass units.

function charge(atom::Atom)¶

Get the charge of an atom.

The charge is in number of the electron charge e.

function set_charge!(atom::Atom, charge)¶

Set the charge of an atom to charge.

The charge must be in number of the electron charge e.

function name(atom::Atom)¶

Get the name of an atom

function set_name!(atom::Atom, name::String)¶

Set the name of an atom to name.

function 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”.

function 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.

function covalent_radius(atom::Atom)¶

Get the covalent radius of an atom from the atom type.

If the radius can not be found, returns -1.

function 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.

function atom_type(atom::Atom)¶

Get the type of an atom.

function set_atom_type!(atom::Atom, atom_type::String)¶

Set the type of an atom to type.

function property(atom::Atom, name::String)¶

Get a named property for the given atom.

function set_property!(atom::Atom, name::String, property)¶

Set a named property for the given atom.

Residue type and associated function¶

type 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.

function Residue(ptr::Ptr{lib.CHFL_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.

function Residue(name::String)¶

Create a new residue with the given name

function Residue(name::String, resid::Integer)¶

Create a new residue with the given name and residue identifier resid.

function 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.

function 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.

function deepcopy(residue::Residue)¶

Make a deep copy of a residue.

function name(residue::Residue)¶

Get the name of a residue.

function id(residue::Residue)¶

Get the identifier of a residue in the initial topology.

function size(residue::Residue)¶

Get the number of atoms in a residue.

function add_atom!(residue::Residue, index::Integer)¶

Add the atom at the given index in the residue.

function contains(residue::Residue, index::Integer)¶

Check if the atom at the given index is in the residue.

function deepcopy(residue::Residue)¶

Make a deep copy of a residue.

Selection type and associated function¶

type 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.

function Selection(ptr::Ptr{lib.CHFL_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.

function Selection(selection::AbstractString)¶

Create a Selection from a selection string

function deepcopy(selection::Selection)¶

Make a deep copy of a selection.

function size(selection::Selection)¶

Get the size of a selection, i.e. the number of atoms we are selecting together.

function evaluate(selection::Selection, frame::Frame)¶

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.

function selection_string(selection::Selection)¶

Get the selection string used to create a given selection.