/ 
HackaMol-0.053
River stage one • 3 direct dependents • 3 total dependents
/ HackaMol::Roles::AtomGroupRole

NAME

HackaMol::Roles::AtomGroupRole - Role for a group of atoms

VERSION

version 0.053

SYNOPSIS

  use HackaMol::AtomGroup;
  use HackaMol::Atom;

  my $atom1 = HackaMol::Atom->new(
      name    => 'O1',
      coords  => [ V( 2.05274, 0.01959, -0.07701 ) ],
      Z       => 8,
  );
  
  my $atom2 = HackaMol::Atom->new(
      name    => 'H1',
      coords  => [ V( 1.08388, 0.02164, -0.12303 ) ],
      Z       => 1,
  );
  
  my $atom3 = HackaMol::Atom->new(
      name    => 'H2',
      coords  => [ V( 2.33092, 0.06098, -1.00332 ) ],
      Z       => 1,
  );
  
  $atom1->push_charges(-0.834);
  $_->push_charges(0.417) foreach ($atom1, $atom2);
  
  # instance of class that consumes the AtomGroupRole 
  
  my $group = HackaMol::AtomGroup->new(atoms=> [$atom1,$atom2,$atom3]);
  
  print $group->count_atoms . "\n"; #3
  print $group->total_charge . "\n"; # 0
  print $group->total_mass . "\n";  
  
  my @atoms = $group->all_atoms;
  
  print $group->dipole_moment . "\n";
  
  $group->do_forall('push_charges',0);
  $group->do_forall('push_coords',$group->COM);

  $group->gt(1); # same as $group->do_forall('t',1);
  
  print $group->dipole_moment . "\n";
  print $group->bin_atoms_name . "\n";
  print $group->unique_atoms . "\n";

  $group->translate(V(10,0,0));

  $group->rotate( V(1,0,0),
                       180,
                  V(0,0,0));

  $group->print_xyz ; #STDOUT

  my $fh = $group->print_xyz("hackagroup.xyz"); #returns filehandle
  $group->print_xyz($fh) foreach (1 .. 9);     # boring VMD movie with 10 frames

DESCRIPTION

The HackaMol AtomGroupRole class provides core methods and attributes for consuming classes that use groups of atoms. The original implementation of this role relied heavily on attributes, builders, and clearers. Such an approach naturally gives fast lookup tables, but the ability to change atoms and coordinates made the role to difficult. Such an approach may be pursued again (without changing the API) in the future after the API has matured. The AtomGroupRole calculates all values for atoms using their own t attributes.

METHODS

do_for_all

pass method and arguments down to atoms in group

$group->do_for_all('t',1); #sets t to 1 for all atoms

gt

integer argument. wraps do_for_all for setting time within group

$group->gt(1);

dipole

no arguments. return dipole calculated from charges and coordinates as Math::Vector::Real object

COM

no arguments. return center of mass calculated from masses and coordinates as Math::Vector::Real object

COZ

no arguments. return center of nuclear charge calculated from Zs and coordinates as Math::Vector::Real object

total_charge

no arguments. return sum of atom charges.

total_mass

no arguments. return sum of atom masses.

total_Z

no arguments. return sum of Zs.

dipole_moment

no arguments. returns the norm of the dipole in debye (assuming charges in electrons, AKMA)

bin_atoms

Called with no arguments. Returns a hash with a count for each unique atom symbol.

count_unique_atoms

no arguments. returns the number of unique atoms

bin_atoms_name

no arguments. returns a string summary of the atoms in the group sorted by decreasing atomic number. For example; OH2 for water or O2H2 for peroxide.

tmax

return (count_coords-1) if > 0; return 0 otherwise; croaks if not all atoms share the same tmax.

translate

requires Math::Vector::Real vector argument. Optional argument: integer tf.

Translates all atoms in group by the MVR vector. Pass tf to the translate method to store new coordinates in tf rather than atom->t.

rotate

requires Math::Vector::Real vector, an angle (in degrees), and a MVR vector origin as arguments. Optional argument: integer tf.

Rotates all atoms in the group around the MVR vector. Pass tf to the translate method to store new coordinates in tf rather than atom->t.

optional argument: filename or filehandle. with no argument, prints xyz formatted output to STDOUT. pass a filename and an xyz file with that name will be written or overwritten (with warning). pass filehandle for continuous writing to an open filehandle.

argument: array_ref containing the values of t to be used for printing. optional argument: filename or filehandle for writing out to file. For example,

$mol->print_xyz_ts([0 .. 3, 8, 4], 'fun.xyz');

will write the coordinates for all group atoms at t=0,1,2,3,8,4 to a file, in that order.

same as print_xyz, but for pdb formatted output

same as print_xyz_ts, but for pdb formatted output

bin_this

argument: Str , return hash_ref of binned $self->Str.

$hash_ref{$_}++ foreach ( map {$_->$Str} $self->all_atoms );

what_time

returns the current setting of t by checking against all members of group.

fix_serial

argument, optional: Int, offset for resetting the serial number of atoms. Returns the offset.

$group->fix_serial(0); # serial starts from zero

centered_vector

calculates least squares fitted vector for the AtomGroup. Returns normalized Math::Vector::Real object with origin V(0,0,0).

$mvr = $group->centered_vector; # unit vector origin 0,0,0 
# place two mercury atoms along the vector to visualize the fit 
my $hg_1 = HackaMol::Atom->new(Z => 80, coords => [$group->center]);
my $hg_2 = HackaMol::Atom->new(Z => 80, coords => [$group->center + $mvr]);

ARRAY METHODS

push_atoms, get_atoms, set_atoms, all_atoms, count_atoms, clear_atoms

ARRAY traits for the atoms attribute, respectively: push, get, set, elements, count, clear

push_atoms, unshift_atoms

push atom on to the end of the atoms array or unshift_atoms on to the front of the array

$group->push_atoms($atom1, $atom2, @otheratoms);
$group->unshift_atoms($atom1, $atom2, @otheratoms); # maybe in reverse

all_atoms

returns array of all elements in atoms array

print $_->symbol, "\n" foreach $group->all_atoms;

get_atoms

return element by index from atoms array

print $group->get_atoms(1); # returns $atom2 from above

set_atoms

set atoms array by index

$group->set_atoms(1, $atom1);

count_atoms

return number of atoms in group

print $group->count_atoms;

clear_atoms

clears atoms array

ATTRIBUTES

atoms

isa ArrayRef[Atom] that is lazy with public ARRAY traits described in ARRAY_METHODS

qcat_print

isa Bool that has a lazy default value of 0. if qcat_print, print all atoms coordinates in one go (no model breaks)

SEE ALSO

AUTHOR

Demian Riccardi <demianriccardi@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by Demian Riccardi.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.