NAME

Chemistry::Mol - Molecule object toolkit

SYNOPSIS

    use Chemistry::Mol;

    $mol = Chemistry::Mol->new(id => "mol_id", name => "my molecule");
    $c = $mol->new_atom(symbol => "C", coords => [0,0,0]); 
    $o = $mol->new_atom(symbol => "O", coords => [0,0,1.23]); 
    $mol->new_bond(atoms => [$c, $o], order => 3);

    print $mol->print;

DESCRIPTION

This package, along with Chemistry::Atom and Chemistry::Bond, includes basic objects and methods to describe molecules.

The core methods try not to enforce a particular convention. This means that only a minimal set of attributes is provided by default, and some attributes have very loosely defined meaning. This is because each program and file type has different idea of what each concept (such as bond and atom type) means. Bonds are defined as a list of atoms (typically two) with an arbitrary type. Atoms are defined by a symbol and a Z, and may have 3D coordinates (2D and internal coming soon).

METHODS

See also Chemistry::Obj for generic attributes.

Chemistry::Mol->new(name => value, ...)

Create a new Mol object with the specified attributes.

    $mol = Chemistry::Mol->new(id => 'm123', name => 'my mol')

is the same as

    Chemistry::Mol->new()
    $mol->id('m123')
    $mol->name('my mol')

$mol->add_atom($atom, ...)

Add one or more Atom objects to the molecule. Returns the last atom added.

$mol->atom_class

Returns the atom class that a molecule or molecule class expects to use by default. Chemistry::Mol objects return "Chemistry::Atom", but subclasses will likely override this method.

$mol->new_atom(name => value, ...)

Shorthand for $mol->add_atom($mol->atom_class->new(name => value, ...));

$mol->delete_atom($atom, ...)

Deletes an atom from the molecule. It automatically deletes all the bonds in which the atom participates as well. $atom can be either a Chemistry::Atom reference or an atom index.

$mol->add_bond($bond, ...)

Add one or more Bond objects to the molecule. Returns the last bond added.

$mol->bond_class

Returns the bond class that a molecule or molecule class expects to use by default. Chemistry::Mol objects return "Chemistry::Bond", but subclasses will likely override this method.

$mol->new_bond(name => value, ...)

Shorthand for $mol->add_bond($mol->bond_class->new(name => value, ...));

$mol->delete_bond($bond, ...)

Deletes a bond from the molecule.

$mol->by_id($id)

Return the atom or bond object with the corresponding id.

$mol->atoms($n1, ...)

Returns the atoms with the given indices, or all by default. Indices start from one, not from zero.

$mol->atoms_by_name($name)

Returns the atoms with the given name (treated as an anchored regular expression).

$mol->sort_atoms($sub_ref)

Sort the atoms in the molecule by using the comparison function given in $sub_ref. This function should take two atoms as parameters and return -1, 0, or 1 depending on whether the first atom should go first, same, or after the second atom. For example, to sort by atomic number, you could use the following:

    $mol->sort( sub { $_[0]->Z <=> $_[1]->Z } );

Note that the atoms are passed as parameters and not as the package variables $a and $b like the core sort function does. This is because $mol->sort will likely be called from another package and we don't want to play with another package's symbol table.

$mol->bonds($n1, ...)

Returns the bonds with the given indices, or all by default. Indices start from one, not from zero.

$mol->print(option => value...)

Convert the molecule to a string representation. If no options are given, a default YAML-like format is used (this may change in the future). Otherwise, the format should be specified by using the format option.

my $info = $mol->sprintf($format)

Format interesting molecular information in a concise way, as specified by a printf-like format.

    %n - name
    %f - formula 
    %f{formula with format} - (note: right braces within
        the format should be escaped with a backslash)
    %s - SMILES representation
    %S - canonical SMILES representation
    %m - mass
    %8.3m - mass, formatted as %8.3f with core sprintf
    %q - formal charge
    %a - atom count
    %b - bond count
    %t - type
    %i - id
    %% - %

For example, if you want just about everything:

    $mol->sprintf("%s - %n (%f). %a atoms, %b bonds; "
        . "mass=%m; charge =%q; type=%t; id=%i");

Note that you have to use Chemistry::File::SMILES before using %s or %S on $mol-sprintf>.

$mol->printf($format)

Same as $mol->sprintf, but prints to standard output automatically. Used for quick and dirty molecular information dumping.

Chemistry::Mol->parse($string, option => value...)

Parse the molecule encoded in $string. The format should be specified with the the format option; otherwise, it will be guessed.

Chemistry::Mol->read($fname, option => value ...)

Read a file and return a list of Mol objects, or croaks if there was a problem. The type of file will be guessed if not specified via the format option.

Note that only registered file readers will be used. Readers may be registered using register_type(); modules that include readers (such as Chemistry::File::PDB) usually register them automatically.

$mol->write($fname, option => value ...)

Write a molecule file, or croak if there was a problem. The type of file will be guessed if not specified via the format option.

Note that only registered file formats will be used.

Chemistry::Mol->register_format($name, $ref)

Register a file type. The identifier $name must be unique. $ref is either a class name (a package) or an object that complies with the Chemistry::File interface (e.g., a subclass of Chemistry::File). If $ref is omitted, the calling package is used automatically. More than one format can be registered at a time, but then $ref must be included for each format (e.g., Chemistry::Mol->register_format(format1 => "package1", format2 => package2).

The typical user doesn't have to care about this function. It is used automatically by molecule file I/O modules.

Chemistry::Mol->formats

Returns a list of the file formats that have been installed by register_type()

$mol->mass

Return the molar mass.

$mol->charge

Return the charge of the molecule. By default it returns the sum of the formal charges of the atoms.

$mol->formula_hash

Returns a hash reference describing the molecular formula. For methane it would return { C => 1, H => 4 }.

$mol->formula($format)

Returns a string with the formula. The format can be specified as a printf-like string with the control sequences specified in the Chemistry::File::Formula documentation.

my $mol2 = $mol->clone;

Makes a copy of a molecule.

($distance, $atom_here, $atom_there) = $mol->distance($obj)

Returns the minimum distance to $obj, which can be an atom, a molecule, or a vector. In scalar context it returns only the distance; in list context it also returns the atoms involved. The current implementation for calculating the minimum distance between two molecules compares every possible pair of atoms, so it's not efficient for large molecules.

my $bigmol = Chemistry::Mol->combine($mol1, $mol2, ...)

$mol1->combine($mol2, $mol3, ...)

Combines several molecules in one bigger molecule. If called as a class method, as in the first example, it returns a new combined molecule without altering any of the parameters. If called as an instance method, as in the second example, all molecules are combined into $mol1 (but $mol2, $mol3, ...) are not altered.

my @mols = $mol->separate

Separates a molecule into "connected fragments". The original object is not modified; the fragments are clones of the original ones. Example: if you have ethane (H3CCH3) and you delete the C-C bond, you have two CH3 radicals within one molecule object ($mol). When you call $mol->separate you get two molecules, each one with a CH3.

VERSION

0.26

SEE ALSO

Chemistry::Atom, Chemistry::Bond, Chemistry::File, Chemistry::Tutorial

The PerlMol website http://www.perlmol.org/

AUTHOR

Ivan Tubert-Brohman <itub@cpan.org>

COPYRIGHT

Copyright (c) 2004 Ivan Tubert-Brohman. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.