blib/lib/Chemistry/Atom.pm

filter: Statementstmt 87.6% 249 / 284 Branchbran 80.0% 72 / 90 Conditioncond 70.2% 26 / 37 MC/DCmcdc 60.8% 14 / 23 Subroutinesub 94.0% 47 / 50 Podpod 88.2% 30 / 34 totaltotal 84.5% 438 / 518 CC 72 SCAR 16.7
CC
72
Cov
84%
distance
13.2
_calc_implicit_hydrogens
13.0
sprintf
8.8
CRAP 5.3
« blib/lib/Parse/Yapp/Parse.pm ↑ Summary blib/lib/Parse/Yapp/Grammar.pm »
1 package Chemistry::Atom;
2  
3 27 $VERSION = '0.35';
4 # $Id: Atom.pm,v 1.41 2005/05/20 19:01:04 itubert Exp $
5  
6 =head1 NAME
7  
8 Chemistry::Atom - Chemical atoms as objects in molecules
9  
10 =head1 SYNOPSIS
11  
12 use Chemistry::Atom;
13  
14 my $atom = new Chemistry::Atom(
15 id => 'a1',
16 coords => [$x, $y, $z],
17 symbol => 'Br'
18 );
19  
20 print $atom->print;
21  
22 =head1 DESCRIPTION
23  
24 This module includes objects to describe chemical atoms.
25 An atom is defined by its symbol and its coordinates, among other attributes.
26 Atomic coordinates are described by a Math::VectorReal
27 object, so that they can be easily used in vector operations.
28  
29 =head2 Atom Attributes
30  
31 In addition to common attributes such as id, name, and type,
32 atoms have the following attributes, which are accessed or
33 modified through methods defined below: bonds, coords, internal_coords,
34 Z, symbol, etc.
35  
36 In general, to get the value of a property, use $atom->method without
37 any parameters. To set the value, use $atom->method($new_value). When setting
38 an attribute, the accessor returns the atom object, so that accessors can be
39 chained:
40  
41 $atom->symbol("C")->name("CA")->coords(1,2,3);
42  
43 =cut
44  
45 # Considering to add the following attributes:
46 # mass_number (A)
47  
48 27 ▶use 5.006;
Subroutine BEGIN: called CC=1 SCAR=0.0
49 27 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
50 27 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
51 27 ▶use Scalar::Util 'weaken';
Subroutine BEGIN: called CC=1 SCAR=0.0
52 27 ▶use Math::VectorReal qw(O vector);
Subroutine BEGIN: called CC=1 SCAR=0.0
53 27 ▶use Math::Trig;
Subroutine BEGIN: called CC=1 SCAR=0.0
54 27 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
55 27 ▶use base qw(Chemistry::Obj Exporter);
Subroutine BEGIN: called CC=1 SCAR=0.0
56 27 ▶use List::Util qw(first);
Subroutine BEGIN: called CC=1 SCAR=0.0
57  
58 27 our @EXPORT_OK = qw(distance angle dihedral angle_deg dihedral_deg);
59 27 our %EXPORT_TAGS = (
60 all => \@EXPORT_OK,
61 );
62  
63  
64  
65 27 my $N = 0; # Number of atoms created so far, used to generate default IDs.
66  
67 27 our @ELEMENTS = qw(
68 n
69 H He
70 Li Be B C N O F Ne
71 Na Mg Al Si P S Cl Ar
72 K Ca Sc Ti V Cr Mn Fe Co Ni Cu Zn Ga Ge As Se Br Kr
73 Rb Sr Y Zr Nb Mo Tc Ru Rh Pd Ag Cd In Sn Sb Te I Xe
74 Cs Ba
75 La Ce Pr Nd Pm Sm Eu Gd Tb Dy Ho Er Tm Yb
76 Lu Hf Ta W Re Os Ir Pt Au Hg Tl Pb Bi Po At Rn
77 Fr Ra
78 Ac Th Pa U Np Pu Am Cm Bk Cf Es Fm Md No
79 Lr Rf Db Sg Bh Hs Mt Ds Uuu Uub Uut Uuq Uup Uuh Uus Uuo
80 );
81  
82 27 our %ELEMENTS;
83 27 ▶for (my $i = 1; $i < @ELEMENTS; ++$i){
Branch: 1 branch
BranchTrueFalseTotal
if ($i < @Chemistry::Atom::ELEMENTS) 3186 27 3213
84 3186 $ELEMENTS{$ELEMENTS[$i]} = $i;
85 }
86 27 $ELEMENTS{D} = $ELEMENTS{T} = 1;
87  
88 27 my %Atomic_masses = (
89 "H" => 1.00794, "D" => 2.014101, "T" => 3.016049, "He" => 4.002602,
90 "Li" => 6.941, "Be" => 9.012182, "B" => 10.811, "C" => 12.0107,
91 "N" => 14.00674, "O" => 15.9994, "F" => 18.9984032, "Ne" => 20.1797,
92 "Na" => 22.989770, "Mg" => 24.3050, "Al" => 26.981538, "Si" => 28.0855,
93 "P" => 30.973761, "S" => 32.066, "Cl" => 35.4527, "Ar" => 39.948,
94 "K" => 39.0983, "Ca" => 40.078, "Sc" => 44.955910, "Ti" => 47.867,
95 "V" => 50.9415, "Cr" => 51.9961, "Mn" => 54.938049, "Fe" => 55.845,
96 "Co" => 58.933200, "Ni" => 58.6934, "Cu" => 63.546, "Zn" => 65.39,
97 "Ga" => 69.723, "Ge" => 72.61, "As" => 74.92160, "Se" => 78.96,
98 "Br" => 79.904, "Kr" => 83.80, "Rb" => 85.4678, "Sr" => 87.62,
99 "Y" => 88.90585, "Zr" => 91.224, "Nb" => 92.90638, "Mo" => 95.94,
100 "Tc" => 98, "Ru" => 101.07, "Rh" => 102.90550, "Pd" => 106.42,
101 "Ag" => 107.8682, "Cd" => 112.411, "In" => 114.818, "Sn" => 118.710,
102 "Sb" => 121.760, "Te" => 127.60, "I" => 126.90447, "Xe" => 131.29,
103 "Cs" => 132.90545, "Ba" => 137.327, "La" => 138.9055, "Ce" => 140.116,
104 "Pr" => 140.90765, "Nd" => 144.24, "Pm" => 145, "Sm" => 150.36,
105 "Eu" => 151.964, "Gd" => 157.25, "Tb" => 158.92534, "Dy" => 162.50,
106 "Ho" => 164.93032, "Er" => 167.26, "Tm" => 168.93421, "Yb" => 173.04,
107 "Lu" => 174.967, "Hf" => 178.49, "Ta" => 180.9479, "W" => 183.84,
108 "Re" => 186.207, "Os" => 190.23, "Ir" => 192.217, "Pt" => 195.078,
109 "Au" => 196.96655, "Hg" => 200.59, "Tl" => 204.3833, "Pb" => 207.2,
110 "Bi" => 208.98038, "Po" => 209, "At" => 210, "Rn" => 222,
111 "Fr" => 223, "Ra" => 226, "Ac" => 227, "Th" => 232.038,
112 "Pa" => 231.03588, "U" => 238.0289, "Np" => 237, "Pu" => 244,
113 "Am" => 243, "Cm" => 247, "Bk" => 247, "Cf" => 251,
114 "Es" => 252, "Fm" => 257, "Md" => 258, "No" => 259,
115 "Lr" => 262, "Rf" => 261, "Db" => 262, "Sg" => 266,
116 "Bh" => 264, "Hs" => 269, "Mt" => 268, "Ds" => 271,
117 );
118  
119 =head1 METHODS
120  
121 =over 4
122  
123 =item Chemistry::Atom->new(name => value, ...)
124  
125 Create a new Atom object with the specified attributes.
126  
127 =cut
128  
129 658 ▶sub new {
Subroutine new: called CC=2 SCAR=6.9
Pod documented
130 658 my $class = shift;
131 658 my %args = @_;
132  
133 658 my $self = bless {
134 id => $class->nextID(),
135 coords => vector(0, 0, 0),
136 Z => 0,
137 symbol => '',
138 bonds => [],
139 }, $class;
140  
141 658 $self->$_($args{$_}) for (keys %args);
142 658 $self;
143 }
144  
145 660 ▶sub nextID {
Subroutine nextID: called CC=1 SCAR=0.0
Pod undocumented
146 660 "a".++$N;
147 }
148  
149 0 ▶sub reset_id {
Subroutine reset_id: not called CC=1 SCAR=6.9
Pod undocumented
150 0 $N = 0;
151 }
152  
153  
154 =item $atom->Z($new_Z)
155  
156 Sets and returns the atomic number (Z). If the symbol of the atom doesn't
157 correspond to a known element, Z = undef.
158  
159 =cut
160  
161 7 ▶sub Z {
Subroutine Z: called CC=2 SCAR=6.9
Pod documented
162 7 my $self = shift;
163  
164 7 ▶ if(@_) {
Branch: 1 branch
BranchTrueFalseTotal
if (@_) { } 4 3 7
165 4 $self->{symbol} = $ELEMENTS[$_[0]];
166 4 $self->{Z} = $_[0];
167 4 return $self;
168 } else {
169 3 return $self->{Z};
170 }
171 }
172  
173  
174 =item $atom->symbol($new_symbol)
175  
176 Sets and returns the atomic symbol.
177  
178 =cut
179  
180 4427 ▶sub symbol {
Subroutine symbol: called CC=2 SCAR=6.9
Pod documented
181 4427 my $self = shift;
182  
183 4427 ▶ if(@_) {
Branch: 1 branch
BranchTrueFalseTotal
if (@_) { } 620 3807 4427
184 620 $_[0] =~ s/ //g;
185 620 $self->{Z} = $ELEMENTS{$_[0]};
186 620 $self->{symbol} = $_[0];
187 620 return $self;
188 } else {
189 3807 return $self->{symbol};
190 }
191 }
192  
193 =item $atom->mass($new_mass)
194  
195 Sets and returns the atomic mass in atomic mass units. Any arbitrary mass may
196 be set explicitly by using this method. However, if no mass is set explicitly
197 and this method is called as an accessor, the return value is the following:
198  
199 1) If the mass number is undefined (see the mass_number method below), the
200 relative atomic mass from the 1995 IUPAC recommendation is used. (Table stolen
201 from the Chemistry::MolecularMass module by Maksim A. Khrapov).
202  
203 2) If the mass number is defined and the L<Chemistry::Isotope> module is
204 available and it knows the mass for the isotope, the exact mass of the isotope
205 is used; otherwise, the mass number is returned.
206  
207 =cut
208  
209 13 ▶sub mass {
Subroutine mass: called CC=6 SCAR=17.9
Pod documented
210 13 my $self = shift;
211 13 ▶ if (@_) {
Branch: 1 branch
BranchTrueFalseTotal
if (@_) { } 2 11 13
212 2 $self->{mass} = shift;
213 2 return $self;
214 } else {
215 11 ▶ if (defined $self->{mass}) {
Branch: 2 branches
BranchTrueFalseTotal
if (defined $self->{'mass'}) { } 2 9 11
elsif (defined $self->{'mass_number'}) { } 2 7 9
216 2 return $self->{mass};
217 } elsif (defined $self->{mass_number}) {
218 2 ▶ if (eval { require Chemistry::Isotope } and
Branch: 1 branch
BranchTrueFalseTotal
if (eval { do { require Chemistry::Isotope } } and my $m = Chemistry::Isotope::isotope_mass($self->{'mass_number'}, $self->{'Z'})) { } 1 1 2
Condition66%2/3
eval { do { require Chemistry::Isotope } } and my $m = Chemistry::Isotope::isotope_mass($self->{"mass_number"}, $self->{"Z"})
!ll&&!rl&&r
011
MC/DC50%1/2
eval { do { require Chemistry::Isotope } } and my $m = Chemistry::Isotope::isotope_mass($self->{"mass_number"}, $self->{"Z"})
eval { do { require Chemistry::Isotope } } my $m = Chemistry::Isotope::isotope_mass($self->{"mass_number"}, $self->{"Z"})
Truth table66%2/3
A and B
A= eval { do { require Chemistry::Isotope } }B= my $m = Chemistry::Isotope::isotope_mass($self->{"mass_number"}, $self->{"Z"})
ABresult
0X0
100
111
219 my $m = Chemistry::Isotope::isotope_mass(
220 $self->{mass_number}, $self->{Z})
221 ) {
222 1 return $m;
223 } else {
224 1 return $self->{mass_number};
225 }
226 } else {
227 7 return $Atomic_masses{$self->symbol};
228 }
229 }
230 }
231  
232 =item $atom->mass_number($new_mass_number)
233  
234 Sets or gets the mass number. The mass number is undefined unless is
235 set explicitly (this module does not try to guess a default mass number based
236 on the natural occuring isotope distribution).
237  
238 =cut
239  
240 27 Chemistry::Obj::accessor('mass_number');
241  
242 =item $atom->coords
243  
244 my $vector = $atom->coords; # get a Math::VectorReal object
245 $atom->coords($vector); # set a Math::VectorReal object
246 $atom->coords([$x, $y, $z]); # also accepts array refs
247 $atom->coords($x, $y, $z); # also accepts lists
248  
249 Sets or gets the atom's coordinates. It can take as a parameter a
250 Math::VectorReal object, a reference to an array, or the list of coordinates.
251  
252 =cut
253  
254 2395 ▶sub coords {
Subroutine coords: called CC=4 SCAR=13.9
Pod documented
255 2395 my $self = shift;
256  
257 2395 ▶ if(@_) {
Branch: 1 branch
BranchTrueFalseTotal
if (@_) { } 133 2262 2395
258 133 ▶ if (UNIVERSAL::isa($_[0], "Math::VectorReal")) {
Branch: 2 branches
BranchTrueFalseTotal
if (UNIVERSAL::isa($_[0], 'Math::VectorReal')) { } 129 4 133
elsif (ref $_[0] eq 'ARRAY') { } 3 1 4
259 129 $self->{coords} = $_[0];
260 } elsif (ref $_[0] eq "ARRAY") {
261 3 $self->{coords} = vector(@{$_[0]});
262 } else {
263 1 $self->{coords} = vector(@_);
264 }
265 } else {
266 2262 return $self->{coords};
267 }
268 133 $self;
269 }
270  
271 =item $atom->internal_coords
272  
273 # get a Chemistry::InternalCoords object
274 my $ic = $atom->internal_coords;
275  
276 # set a Chemistry::InternalCoords object
277 $atom->internal_coords($vic);
278  
279 # also accepts array refs
280 $atom->internal_coords([8, 1.54, 7, 109.47, 6, 120.0]);
281  
282 # also accepts lists
283 $atom->internal_coords(8, 1.54, 7, 109.47, 6, 120.0);
284  
285 Sets or gets the atom's internal coordinates. It can take as a parameter a
286 Chemistry::InternalCoords object, a reference to an array, or the list of
287 coordinates. In the last two cases, the list elements are the following: atom
288 number or reference for distance, distance, atom number or reference for angle,
289 angle in degrees, atom number or reference for dihedral, dihedral in degrees.
290  
291 =cut
292  
293 547 ▶sub internal_coords {
Subroutine internal_coords: called CC=4 SCAR=17.3
Pod documented
294 547 my $self = shift;
295  
296 547 ▶ if(@_) {
Branch: 1 branch
BranchTrueFalseTotal
if (@_) { } 127 420 547
297 127 ▶ if (UNIVERSAL::isa($_[0], "Chemistry::InternalCoords")) {
Branch: 2 branches
BranchTrueFalseTotal
if (UNIVERSAL::isa($_[0], 'Chemistry::InternalCoords')) { } 127 0 127
elsif (ref $_[0] eq 'ARRAY') { } 0 0 0
298 127 $self->{internal_coords} = $_[0];
299 } elsif (ref $_[0] eq "ARRAY") {
300 0 require Chemistry::InternalCoords;
301 $self->{internal_coords} =
302 0 Chemistry::InternalCoords->new($self, @{$_[0]});
303 } else {
304 0 require Chemistry::InternalCoords;
305 $self->{internal_coords} =
306 0 Chemistry::InternalCoords->new($self, @_);
307 }
308 } else {
309 420 return $self->{internal_coords};
310 }
311 127 $self;
312 }
313  
314 =item $atom->x3, $atom->y3, $atom->z3
315  
316 Get the x, y or z 3D coordinate of the atom. This methods are just accessors
317 that don't change the coordinates. $atom->x3 is short for
318 ($atom->coords->array)[0], and so on.
319  
320 =cut
321  
322 2 ▶sub x3 { ($_[0]->coords->array)[0] }
Subroutine x3: called CC=1 SCAR=0.0
Pod documented
323 2 ▶sub y3 { ($_[0]->coords->array)[1] }
Subroutine y3: called CC=1 SCAR=0.0
Pod documented
324 2 ▶sub z3 { ($_[0]->coords->array)[2] }
Subroutine z3: called CC=1 SCAR=0.0
Pod documented
325  
326 =item $atom->formal_charge($charge)
327  
328 Set or get the formal charge of the atom.
329  
330 =cut
331  
332 27 Chemistry::Obj::accessor('formal_charge');
333  
334 =item $atom->formal_radical($radical)
335  
336 Set or get the formal radical multiplicity for the atom.
337  
338 =cut
339  
340 27 Chemistry::Obj::accessor('formal_radical');
341  
342 =item $atom->implicit_hydrogens($h_count)
343  
344 Set or get the number of implicit hydrogen atoms bonded to the atom.
345  
346 =cut
347  
348 362 ▶sub implicit_hydrogens { shift->hydrogens(@_) }
Subroutine implicit_hydrogens: called CC=1 SCAR=0.0
Pod documented
349  
350 =item $atom->hydrogens($h_count)
351  
352 Set or get the number of implicit hydrogen atoms bonded to the atom
353 (DEPRECATED: USE C<implicit_hydrogens> INSTEAD).
354  
355 =cut
356  
357 27 Chemistry::Obj::accessor('hydrogens');
358  
359 =item $atom->total_hydrogens($h_count)
360  
361 Get the total number of hydrogen atoms bonded to the atom (implicit +
362 explicit).
363  
364 =cut
365  
366 5 ▶sub total_hydrogens {
Subroutine total_hydrogens: called CC=1 SCAR=0.0
Pod documented
367 5 my ($self) = @_;
368 27 ▶ no warnings 'uninitialized';
Subroutine BEGIN: called CC=1 SCAR=0.0
369 5 $self->hydrogens + grep { $_->symbol eq 'H' } $self->neighbors;
370 }
371  
372 =item $atom->sprout_hydrogens
373  
374 Convert all the implicit hydrogens for this atom to explicit hydrogens. Note:
375 it does B<not> generate coordinates for the new atoms.
376  
377 =cut
378  
379 42 ▶sub sprout_hydrogens {
Subroutine sprout_hydrogens: called CC=3 SCAR=11.0
Pod documented
380 42 my ($self) = @_;
381 42 ▶ for (1 .. $self->implicit_hydrogens || 0) {
Condition100%2/2
$self->implicit_hydrogens || 0
l!l
384
MC/DC100%1/1
$self->implicit_hydrogens || 0
$self->implicit_hydrogens
Truth table100%2/2
A
A= $self->implicit_hydrogens
Aresult
11
00
382 91 $self->parent->new_bond(
383 atoms => [$self, $self->parent->new_atom(symbol => 'H')]);
384 }
385 42 $self->implicit_hydrogens(0);
386 }
387  
388 =item $atom->collapse_hydrogens
389  
390 Delete neighboring hydrogen atoms and add them as implicit hydrogens for this
391 atom.
392  
393 =cut
394  
395 40 ▶sub collapse_hydrogens {
Subroutine collapse_hydrogens: called CC=3 SCAR=11.0
Pod documented
396 40 my ($self) = @_;
397 27 ▶ no warnings 'uninitialized';
Subroutine BEGIN: called CC=1 SCAR=0.0
398 40 my $implicit = $self->implicit_hydrogens;
399 40 for my $nei ($self->neighbors) {
400 54 ▶ $nei->delete, $implicit++ if $nei->symbol eq 'H';
Branch: 1 branch
BranchTrueFalseTotal
if $nei->symbol eq "H" 4 50 54
401 }
402 40 $self->implicit_hydrogens($implicit);
403 }
404  
405 27 my %VALENCE_TABLE = (
406 Br => 1, Cl => 1, B => 3, C => 4, N => 3, O => 2, P => 3, S => 2,
407 F => 1, I => 1,
408 );
409  
410 # to make it easier to test
411 17 ▶sub _calc_implicit_hydrogens {
Subroutine _calc_implicit_hydrogens: called CC=13 SCAR=25.7
412 17 my ($self, $symbol, $valence, $charge, $radical) = @_;
413 27 ▶ no warnings 'uninitialized';
Subroutine BEGIN: called CC=1 SCAR=0.0
414  
415 17 my $h_count = $VALENCE_TABLE{$symbol} - $valence;
416 # should account for non-kekulized aromatic bonds
417  
418 # some common charge situations
419 17 ▶ if (($symbol =~ /^[NOS]$/) && $charge == -1) {
Branch: 4 branches
BranchTrueFalseTotal
if ($symbol =~ /^[NOS]$/ and $charge == -1) { } 3 14 17
elsif ($symbol =~ /^[NOSP]$/ and $charge == 1) { } 4 10 14
elsif ($symbol eq 'C' and $charge) { } 2 8 10
elsif ($symbol eq 'B' and $charge == -1) { } 1 14 15
Condition100%3/3
$symbol =~ /^[NOS]$/ and $charge == -1
!ll&&!rl&&r
953
MC/DC100%2/2
$symbol =~ /^[NOS]$/ and $charge == -1
$symbol =~ /^[NOS]$/ $charge == -1
Truth table100%3/3
A and B
A= $symbol =~ /^[NOS]$/B= $charge == -1
ABresult
0X0
100
111
420 3 $h_count--;
421 ▶ } elsif ($symbol =~ /^[NOSP]$/ && $charge == 1) {
Condition100%3/3
$symbol =~ /^[NOSP]$/ and $charge == 1
!ll&&!rl&&r
914
MC/DC100%2/2
$symbol =~ /^[NOSP]$/ and $charge == 1
$symbol =~ /^[NOSP]$/ $charge == 1
Truth table100%3/3
A and B
A= $symbol =~ /^[NOSP]$/B= $charge == 1
ABresult
0X0
100
111
422 4 $h_count++;
423 ▶ } elsif ($symbol eq 'C' && $charge) {
Condition100%3/3
$symbol eq "C" and $charge
!ll&&!rl&&r
262
MC/DC100%2/2
$symbol eq "C" and $charge
$symbol eq "C" $charge
Truth table100%3/3
A and B
A= $symbol eq "C"B= $charge
ABresult
0X0
100
111
424 2 $h_count--;
425 ▶ } elsif ($symbol eq 'B' && $charge == -1) {
Condition66%2/3
$symbol eq "B" and $charge == -1
!ll&&!rl&&r
701
MC/DC50%1/2
$symbol eq "B" and $charge == -1
$symbol eq "B" $charge == -1
Truth table66%2/3
A and B
A= $symbol eq "B"B= $charge == -1
ABresult
0X0
100
111
426 1 $h_count++;
427 }
428  
429 # some common radical situations
430 17 ▶ if ($radical == 1 or $radical == 3) {
Branch: 2 branches
BranchTrueFalseTotal
if ($radical == 1 or $radical == 3) { } 3 14 17
elsif ($radical == 2) { } 1 13 14
Condition100%3/3
$radical == 1 or $radical == 3
l!l&&r!l&&!r
1214
MC/DC100%2/2
$radical == 1 or $radical == 3
$radical == 1 $radical == 3
Truth table100%3/3
A or B
A= $radical == 1B= $radical == 3
ABresult
1X1
011
000
431 3 $h_count -=2;
432 } elsif ($radical == 2) {
433 1 $h_count--;
434 }
435  
436 17 ▶ $h_count = 0 if $h_count < 0;
Branch: 1 branch
BranchTrueFalseTotal
if $h_count < 0 0 17 17
437 17 $h_count;
438 }
439  
440 =item $atom->calc_implicit_hydrogens
441  
442 Use heuristics to figure out how many implicit hydrogens should the atom have
443 to satisfy its normal "organic" valence. Returns the number of hydrogens but
444 does not affect the atom object.
445  
446 =cut
447  
448 3 ▶sub calc_implicit_hydrogens {
Subroutine calc_implicit_hydrogens: called CC=1 SCAR=0.0
Pod documented
449 3 my ($self) = @_;
450 3 $self->_calc_implicit_hydrogens(
451 $self->symbol, $self->explicit_valence,
452 $self->formal_charge, $self->formal_radical,
453 );
454 }
455  
456 =item $atom->add_implicit_hydrogens
457  
458 Similar to calc_implicit_hydrogens, but it also sets the number of implicit
459 hydrogens in the atom to the new calculated value. Equivalent to
460  
461 $atom->implicit_hydrogens($atom->calc_implicit_hydrogens);
462  
463 It returns the atom object.
464  
465 =cut
466  
467 3 ▶sub add_implicit_hydrogens {
Subroutine add_implicit_hydrogens: called CC=1 SCAR=0.0
Pod documented
468 3 my ($self) = @_;
469 3 my $h_count = $self->calc_implicit_hydrogens;
470 3 $self->implicit_hydrogens($h_count);
471 }
472  
473 =item $atom->aromatic($bool)
474  
475 Set or get whether the atom is considered to be aromatic. This property may be
476 set arbitrarily, it doesn't imply any kind of "intelligent aromaticity
477 detection"! (For that, look at the L<Chemistry::Ring> module).
478  
479 =cut
480  
481 27 Chemistry::Obj::accessor('aromatic');
482  
483 =item $atom->valence
484  
485 Returns the sum of the bond orders of the bonds in which the atom participates,
486 including implicit hydrogens (which are assumed to have bond orders of one).
487  
488 =cut
489  
490 81 ▶sub valence {
Subroutine valence: called CC=3 SCAR=11.0
Pod documented
491 81 my ($self) = @_;
492 81 my $valence = 0;
493 81 $valence += $_->order for $self->bonds;
494 81 ▶ $valence += $self->hydrogens || 0;
Condition100%2/2
$self->hydrogens || 0
l!l
3843
MC/DC100%1/1
$self->hydrogens || 0
$self->hydrogens
Truth table100%2/2
A
A= $self->hydrogens
Aresult
11
00
495 81 $valence;
496 }
497  
498 =item $atom->explicit_valence
499  
500 Like C<valence>, but excluding implicit hydrogen atoms. To get the raw number
501 of bonds, without counting bond orders, call $atom->bonds in scalar context.
502  
503 =cut
504  
505 6 ▶sub explicit_valence {
Subroutine explicit_valence: called CC=2 SCAR=6.9
Pod documented
506 6 my ($self) = @_;
507 6 my $valence = 0;
508 6 $valence += $_->order for $self->bonds;
509 6 $valence;
510 }
511  
512 # this method is for internal use only; called by $mol->add_bond
513 290 ▶sub add_bond {
Subroutine add_bond: called CC=3 SCAR=11.0
Pod undocumented
514 290 my $self = shift;
515 290 my $bond = shift;
516 290 my %seen;
517 #return if first { $_ eq $bond } @{$self->{bonds}};
518  
519 290 for my $atom (@{$bond->{atoms}}){ #for each atom...
520 580 ▶ if ($atom ne $self) {
Branch: 1 branch
BranchTrueFalseTotal
if ($atom ne $self) 290 290 580
521 290 my $b = {to=>$atom, bond=>$bond};
522 290 weaken($b->{to});
523 290 weaken($b->{bond});
524 290 push @{$self->{bonds}}, $b;
525 }
526 }
527 }
528  
529 # make sure the atom doesn't cause circular references
530 121 ▶sub _weaken {
Subroutine _weaken: called CC=2 SCAR=6.9
531 121 my $self = shift;
532 121 for my $b (@{$self->{bonds}}) {
533 168 weaken($b->{to});
534 168 weaken($b->{bond});
535 }
536 121 weaken($self->{parent});
537 }
538  
539 # This method is private. Bonds should be deleted from the
540 # mol object. These methods should only be called by
541 # $bond->delete_atoms, which is called by $mol->delete_bond
542 28 ▶sub delete_bond {
Subroutine delete_bond: called CC=1 SCAR=0.0
Pod undocumented
543 28 my ($self, $bond) = @_;
544 28 $self->{bonds} = [ grep { $_->{bond} ne $bond } @{$self->{bonds}} ];
545 }
546  
547 =item $atom->delete
548  
549 Calls $mol->delete_atom($atom) on the atom's parent molecule.
550  
551 =cut
552  
553 7 ▶sub delete {
Subroutine delete: called CC=1 SCAR=0.0
Pod documented
554 7 my ($self) = @_;
555 7 $self->{parent}->_delete_atom($self);
556 }
557  
558 =item $atom->parent
559  
560 Returns the atom's containing object (the molecule to which the atom belongs).
561 An atom can only have one parent.
562  
563 =cut
564  
565 913 ▶sub parent {
Subroutine parent: called CC=2 SCAR=6.9
Pod documented
566 913 my $self = shift;
567 913 ▶ if (@_) {
Branch: 1 branch
BranchTrueFalseTotal
if (@_) { } 675 238 913
568 675 ($self->{parent}) = @_;
569 675 weaken($self->{parent});
570 675 $self;
571 } else {
572 238 $self->{parent};
573 }
574 }
575  
576 =item $atom->neighbors($from)
577  
578 Return a list of neighbors. If an atom object $from is specified, it will be
579 excluded from the list (this is useful if an atom wants to know who its
580 neighbor's neighbors are, without counting itself).
581  
582 =cut
583  
584 276 ▶sub neighbors {
Subroutine neighbors: called CC=4 SCAR=13.9
Pod documented
585 276 my $self = shift;
586 276 my $from = shift;
587 276 my @ret = ();
588  
589 276 for my $b (@{$self->{bonds}}) {
590 622 ▶ push @ret, $b->{to} unless $from && $b->{to} eq $from;
Branch: 1 branch
BranchTrueFalseTotal
unless $from and $b->{"to"} eq $from 488 134 622
Condition100%3/3
$from and $b->{"to"} eq $from
!ll&&!rl&&r
161327134
MC/DC100%2/2
$from and $b->{"to"} eq $from
$from $b->{"to"} eq $from
Truth table100%3/3
A and B
A= $fromB= $b->{"to"} eq $from
ABresult
0X0
100
111
591 }
592 276 @ret;
593 }
594  
595 =item $atom->bonds($from)
596  
597 Return a list of bonds. If an atom object $from is specified, bonds to
598 that atom will be excluded from the list.
599  
600 =cut
601  
602 1512 ▶sub bonds {
Subroutine bonds: called CC=4 SCAR=14.5
Pod documented
603 1512 my $self = shift;
604 1512 my $from = shift;
605 1512 my @ret = ();
606  
607 1512 for my $b (@{$self->{bonds}}) {
608 4677 ▶ push @ret, $b->{bond} unless $from && $b->{to} eq $from;
Branch: 1 branch
BranchTrueFalseTotal
unless $from and $b->{"to"} eq $from 4677 0 4677
Condition33%1/3
$from and $b->{"to"} eq $from
!ll&&!rl&&r
467700
MC/DC0%0/2
$from and $b->{"to"} eq $from
$from $b->{"to"} eq $from
Truth table33%1/3
A and B
A= $fromB= $b->{"to"} eq $from
ABresult
0X0
100
111
609 }
610 1512 @ret;
611 }
612  
613 =item $atom->bonds_neighbors($from)
614  
615 Return a list of hash references, representing the bonds and neighbors from the
616 atom. If an atom object $from is specified, it will be excluded from the list.
617 The elements of the hash are 'to', and atom reference, and 'bond', a bond
618 reference. For example,
619  
620 for my $bn ($atom->bonds_neighbors) {
621 print "bond $bn->{bond} point to atom $bn->{to}\n";
622 }
623  
624 =cut
625  
626 9456 ▶sub bonds_neighbors {
Subroutine bonds_neighbors: called CC=4 SCAR=14.5
Pod documented
627 9456 my $self = shift;
628 9456 my $from = shift;
629 9456 my @ret = ();
630  
631 9456 for my $b (@{$self->{bonds}}) {
632 30058 ▶ push @ret, {%$b} unless $from && $b->{to} eq $from;
Branch: 1 branch
BranchTrueFalseTotal
unless $from and $b->{"to"} eq $from 30058 0 30058
Condition33%1/3
$from and $b->{"to"} eq $from
!ll&&!rl&&r
3005800
MC/DC0%0/2
$from and $b->{"to"} eq $from
$from $b->{"to"} eq $from
Truth table33%1/3
A and B
A= $fromB= $b->{"to"} eq $from
ABresult
0X0
100
111
633 }
634 9456 @ret;
635 }
636  
637 =item ($distance, $closest_atom) = $atom->distance($obj)
638  
639 Returns the minimum distance to $obj, which can be an atom, a molecule, or a
640 vector. In scalar context it returns only the distance; in list context it
641 also returns the closest atom found. It can also be called as a function,
642 Chemistry::Atom::distance (which can be exported).
643  
644 =cut
645  
646 118 ▶sub distance {
Subroutine distance: called CC=8 SCAR=25.8
Pod documented
647 118 my $self = shift;
648 118 my $obj = shift;
649 118 my $min_length;
650 118 my $closest_atom = $obj;
651  
652 118 ▶ if ($obj->isa('Chemistry::Atom')) {
Branch: 3 branches
BranchTrueFalseTotal
if ($obj->isa('Chemistry::Atom')) { } 116 2 118
elsif ($obj->isa('Math::VectorReal')) { } 1 1 2
elsif ($obj->isa('Chemistry::Mol')) { } 0 1 1
653 116 my $v = $self->coords - $obj->coords;
654 116 $min_length = $v->length;
655 } elsif ($obj->isa('Math::VectorReal')) {
656 1 my $v = $self->coords - $obj;
657 1 $min_length = $v->length;
658 } elsif ($obj->isa('Chemistry::Mol')) {
659 0 my @atoms = $obj->atoms;
660 0 ▶ my $a = shift @atoms or return undef; # ensure there's at least 1 atom
Branch: 1 branch
BranchTrueFalseTotal
my $a = shift @atoms or return undef 0 0 0
661 0 $min_length = $self->distance($a);
662 0 $closest_atom = $a;
663 0 for $a (@atoms) {
664 0 my $l = $self->distance($a);
665 0 ▶ $min_length = $l, $closest_atom = $a if $l < $min_length;
Branch: 1 branch
BranchTrueFalseTotal
if $l < $min_length 0 0 0
666 }
667 } else {
668 1 croak "atom->distance() undefined for objects of type '", ref $obj,"'";
669 }
670 117 ▶ wantarray ? ($min_length, $closest_atom) : $min_length;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 0 117 117
671 }
672  
673 =item $atom->angle($atom2, $atom3)
674  
675 Returns the angle in radians between the atoms involved. $atom2 is the atom in
676 the middle. Can also be called as Chemistry::Atom::angle($atom1, $atom2,
677 $atom3). This function can be exported. Note: if you override this method,
678 you may also need to override angle_deg or strange things may happen.
679  
680 =cut
681  
682 # $a2 is the one in the center
683 483 ▶sub angle {
Subroutine angle: called CC=7 SCAR=19.5
Pod documented
684 483 ▶ @_ == 3 or croak "Chemistry::Atom::angle requires three atoms!\n";
Branch: 1 branch
BranchTrueFalseTotal
@_ == 3 or croak("Chemistry::Atom::angle requires three atoms!\n") 482 1 483
685 482 my @c;
686 482 for my $a (@_) { # extract coordinates
687 1444 ▶ ref $a or croak "Chemistry::Atom::angle: $a is not an object";
Branch: 1 branch
BranchTrueFalseTotal
ref $a or croak("Chemistry::Atom::angle: $a is not an object") 1443 1 1444
688 1443 ▶ push @c, $a->isa("Chemistry::Atom") ? $a->coords :
Branch: 2 branches
BranchTrueFalseTotal
$a->isa('Chemistry::Atom') ? : 566 877 1443
$a->isa('Math::VectorReal') ? : 876 1 877
689 $a->isa("Math::VectorReal") ? $a :
690 croak "angle: $a is neither an atom nor a vector!\n";
691 }
692 480 my $v1 = $c[0] - $c[1];
693 480 my $v2 = $c[2] - $c[1];
694 480 ▶ my $l = ($v1->length * $v2->length) or return 0;
Branch: 1 branch
BranchTrueFalseTotal
my $l = $v1->length * $v2->length or return 0 476 4 480
695 476 acos(($v1 . $v2) / $l);
696 }
697  
698 =item $atom->angle_deg($atom2, $atom3)
699  
700 Same as angle(), but returns the value in degrees. May be exported.
701  
702 =cut
703  
704 189 ▶sub angle_deg {
Subroutine angle_deg: called CC=1 SCAR=0.0
Pod documented
705 189 rad2deg(angle(@_));
706 }
707  
708 =item $atom->dihedral($atom2, $atom3, $atom4)
709  
710 Returns the dihedral angle in radians between the atoms involved. Can also be
711 called as Chemistry::Atom::dihedral($atom1, $atom2, $atom3, $atom4). May be
712 exported. Note: if you override this method, you may also need to override
713 dihedral_deg and angle or strange things may happen.
714  
715 =cut
716  
717 289 ▶sub dihedral {
Subroutine dihedral: called CC=6 SCAR=17.9
Pod documented
718 289 ▶ @_ == 4 or croak "Chemistry::Atom::dihedral requires four atoms!\n";
Branch: 1 branch
BranchTrueFalseTotal
@_ == 4 or croak("Chemistry::Atom::dihedral requires four atoms!\n") 288 1 289
719 288 my @c;
720 288 for my $a (@_) { # extract coordinates
721 1152 ▶ push @c, $a->isa("Chemistry::Atom") ? $a->coords :
Branch: 2 branches
BranchTrueFalseTotal
$a->isa('Chemistry::Atom') ? : 1144 8 1152
$a->isa('Math::VectorReal') ? : 8 0 8
722 $a->isa("Math::VectorReal") ? $a :
723 croak "angle: $a is neither an atom nor a vector!\n";
724 }
725 288 my $v1 = $c[0] - $c[1];
726 288 my $v2 = $c[2] - $c[1];
727 288 my $v3 = $c[3] - $c[2];
728 288 my $x1 = $v1 x $v2;
729 288 my $x2 = $v3 x $v2;
730 288 my $abs_dih = angle($x1, O(), $x2);
731 288 ▶ $v1 . $x2 > 0 ? $abs_dih : -$abs_dih;
Branch: 1 branch
BranchTrueFalseTotal
$v1 . $x2 > 0 ? : 156 132 288
732 }
733  
734 =item $atom->dihedral_deg($atom2, $atom3, $atom4)
735  
736 Same as dihedral(), but returns the value in degrees. May be exported.
737  
738 =cut
739  
740 286 ▶sub dihedral_deg {
Subroutine dihedral_deg: called CC=1 SCAR=0.0
Pod documented
741 286 rad2deg(dihedral(@_));
742 }
743  
744 =item $atom->print
745  
746 Convert the atom to a string representation (used for debugging).
747  
748 =cut
749  
750 0 ▶sub print {
Subroutine print: not called CC=2 SCAR=14.8
Pod documented
751 0 my $self = shift;
752 0 my ($indent) = @_;
753  
754 27 ▶ no warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
755 0 ▶ $indent ||= 0;
Condition0%0/2
$indent ||= 0
l!l
00
MC/DC0%0/1
$indent ||= 0
$indent
Truth table0%0/2
A
A= $indent
Aresult
11
00
756 0 my $bonds = join " ", map {$_->id} $self->bonds;
757 0 my $neighbors = join " ", map {$_->id} $self->neighbors;
758 my $coords = $self->{coords}->stringify(
759 0 'x3: %g
760 y3: %g
761 z3: %g'
762 );
763  
764 0 my $ret = <<EOF;
765 $self->{id}:
766 symbol: $self->{symbol}
767 name : $self->{name}
768 $coords
769 formal_charge: $self->{formal_charge}
770 bonds: "$bonds"
771 neighbors: "$neighbors"
772 EOF
773 0 $ret .= " attr:\n";
774 0 $ret .= $self->print_attr($indent+2);
775 0 $ret =~ s/^/" "x$indent/gem;
776 0 $ret;
777 }
778  
779 =item my $info = $atom->sprintf($format)
780  
781 Format interesting atomic information in a concise way, as specified by
782 a printf-like format.
783  
784 %s - symbol
785 %Z - atomic number
786 %n - name
787 %q - formal charge
788 %h - implicit hydrogen count
789 %v - valence
790 %i - id
791 %8.3m - mass, formatted as %8.3f with core sprintf
792 %8.3x - x coordinate, formatted as %8.3f with core sprintf
793 %8.3y - y coordinate, formatted as %8.3f with core sprintf
794 %8.3z - z coordinate, formatted as %8.3f with core sprintf
795 %% - %
796  
797 =cut
798  
799 3 ▶sub sprintf {
Subroutine sprintf: called CC=7 SCAR=21.8
Pod documented
800 3 my ($atom, $format) = @_;
801 27 ▶ no warnings 'uninitialized'; # don't care if some properties are undefined
Subroutine BEGIN: called CC=1 SCAR=0.0
802 3 ▶ $format ||= "%f";
Condition50%1/2
$format ||= "%f"
l!l
30
MC/DC0%0/1
$format ||= "%f"
$format
Truth table50%1/2
A
A= $format
Aresult
11
00
803 3 $format =~ s/%%/\\%/g; # escape %% with a \
804 0 ▶ $format =~ s/(?<!\\)%q/$atom->formal_charge || 0/eg; # %q
Condition0%0/2
$atom->formal_charge || 0
l!l
00
MC/DC0%0/1
$atom->formal_charge || 0
$atom->formal_charge
Truth table0%0/2
A
A= $atom->formal_charge
Aresult
11
00
805 3 $format =~ s/(?<!\\)%s/$atom->symbol/eg; # %s
806 3 $format =~ s/(?<!\\)%Z/$atom->Z/eg; # %Z
807 0 $format =~ s/(?<!\\)%n/$atom->name/eg; # %n
808 0 $format =~ s/(?<!\\)%h/$atom->hydrogens/eg; # %h
809 0 $format =~ s/(?<!\\)%v/$atom->valence/eg; # %v
810 3 $format =~ s/(?<!\\)%(\d*\.?\d*)m/
811 0 ▶ $1 ? sprintf "%$1f", $atom->mass : $atom->mass/eg; # %m
Branch: 1 branch
BranchTrueFalseTotal
$1 ? : 0 0 0
812 3 $format =~ s/(?<!\\)%(\d*\.?\d*)x/
813 1 ▶ $1 ? sprintf "%$1f", $atom->x3 : $atom->x3/eg; # %x
Branch: 1 branch
BranchTrueFalseTotal
$1 ? : 0 1 1
814 3 $format =~ s/(?<!\\)%(\d*\.?\d*)y/
815 1 ▶ $1 ? sprintf "%$1f", $atom->y3 : $atom->y3/eg; # %y
Branch: 1 branch
BranchTrueFalseTotal
$1 ? : 0 1 1
816 3 $format =~ s/(?<!\\)%(\d*\.?\d*)z/
817 1 ▶ $1 ? sprintf "%$1f", $atom->z3 : $atom->z3/eg; # %z
Branch: 1 branch
BranchTrueFalseTotal
$1 ? : 0 1 1
818 0 $format =~ s/(?<!\\)%i/$atom->id/eg; # %i
819 3 $format =~ s/\\(.)/$1/g; # other \ escapes
820 3 $format;
821 }
822  
823 =item $atom->printf($format)
824  
825 Same as $atom->sprintf, but prints to standard output automatically. Used
826 for quick and dirty atomic information dumping.
827  
828 =cut
829  
830 0 ▶sub printf {
Subroutine printf: not called CC=1 SCAR=6.9
Pod documented
831 0 my ($atom, $format) = @_;
832 0 print $atom->sprintf($format);
833 }
834  
835 27 1;
836  
837 =back
838  
839 =head1 VERSION
840  
841 0.35
842  
843 =head1 SEE ALSO
844  
845 L<Chemistry::Mol>, L<Chemistry::Bond>,
846 L<Math::VectorReal>, L<Chemistry::Tutorial>,
847 L<Chemistry::InternalCoords>
848  
849 The PerlMol website L<http://www.perlmol.org/>
850  
851 =head1 AUTHOR
852  
853 Ivan Tubert-Brohman E<lt>itub@cpan.orgE<gt>
854  
855 =head1 COPYRIGHT
856  
857 Copyright (c) 2005 Ivan Tubert-Brohman. All rights reserved. This program is
858 free software; you can redistribute it and/or modify it under the same terms as
859 Perl itself.
860  
861 =cut
862  
« blib/lib/Parse/Yapp/Parse.pm ↑ Summary blib/lib/Parse/Yapp/Grammar.pm »