aims 0.2.0

data/README.rdoc

@@ -0,0 +1,100 @@
+
+= What is the Aims Gem?
+
+The Aims gem is a ruby interface to the FHI-Aims ab-initio molecular simulation package published by the Fritz-Haber Institute [https://aimsclub.fhi-berlin.mpg.de/]. It provides a set of tools for parsing and generating the input and output files for AIMS. 
+
+The aims gem is written by Joshua Shapiro and release under the MIT license.
+
+Copyright (c) Joshua Shapiro 2012
+
+= Why should I use the Aims Gem?
+
+If you like Ruby, and you like AIMS, then this gem provides you with a pure Ruby object-oriented interface to AIMS.  You can use this library to: 
+
+* Simplify the generation of complex geometries
+  * Bulk and common surface geometries of ZincBlende and Wurtzite are predefined.
+* Automate the generation of geometry and control files
+* Parse the output of Aims into ruby objects for analysis
+* Summarize the output of AIMS using simple scripts that come with the gem
+* Whatever else you can imagine..
+
+= Installation
+
+To use this gem, you will need to have an installation of ruby.  If you own a mac or a linux machine, then you already have ruby.  If you have a windows machine, then you need to install ruby.  The recommended way to install Ruby on windows (as of June 2012) is via http://rubyinstaller.org .
+
+Once you have ruby, then just invoke the following from a terminal window.
+
+  gem install aims
+
+= Usage 
+== Using the Aims GEM to generate geometry.in files
+
+The following code can be used interactively in an +irb+ ruby interpreter, or can be
+invoked in a ruby script.
+
+=== Example 1: Generate a primitive unit cell of Silicon
+
+  require 'aims'
+  include Aims
+
+  # Define the lattice constant
+  lattice_const = 5.43
+  
+  # Define the basis
+  a1 = Atom.new(0,0,0, "Si")
+  a2 = Atom.new(lattice_const/4, lattice_const/4, lattice_const/4, "Si")
+  
+  # Define the primitive vectors
+  v1 = [lattice_const/2, lattice_const/2, 0]
+  v2 = [lattice_const/2, 0, lattice_const/2]
+  v3 = [0, lattice_const/2, lattice_const/2]
+
+  # Define the unit cell
+  uc = Geometry.new([a1, a2], [v1, v2, v3])
+
+  # Output the unit cell
+  puts uc.format_geometry_in
+
+=== Example 2: Shortcut for generating a primitive unit cell of Zinc-Blende
+
+  require 'aims'
+  include Aims
+  
+  zb = ZincBlende.new("Ga", "As", 5.65)
+  
+  # Get the bulk geometry
+  puts zb.get_bulk.format_geometry_in
+
+And here is how you get a (100) surface with 7 layers and 20 angstrom of vacuum 
+  layers = 7
+  vacuum = 20
+  puts zb.get_001_surface(layers, vacuum)
+  
+And here is how you can constrain the bottom three layers
+  constrain = 3
+  puts zb.get_001_surface(layers, vacuum, constrain)
+  
+== Scripts that come with the Aims GEM
+
+There are currently two scripts that come with the GEM
+
+=== aims_output.rb
+Quickly output the total energy, and timing information from the
+calculation to make sure everything went smoothly.  
+Don't use this as a replacement for actually looking at the output of Aims.
+
+  usage: aims_output.rb [options] file1 [file2 ...]
+      -s, --step [N]                   Output information for relaxation step.
+                                       Specify an integer, 'first', 'last', or 'all'
+                                       Default is 'all'
+          --debug                      Debug output
+          --geometry-delta             Display change from input geometry to final geometry
+      -c, --self-consistency           Output self-consistency information
+      -f                               Output max force component for each geometry relaxation step
+      -t                               Output timings
+
+=== aims_summary.rb
+Display a one-line summary for a list of calculations in tabular form.
+Useful for copying and pasting into a spreadsheet.
+
+    usage: aims_summary.rb file1 [file2] ...

data/bin/aims_output.rb

@@ -0,0 +1,175 @@
+#!/usr/bin/env ruby
+
+require 'optparse'
+require 'aims'
+
+
+
+options = {:step => :all}
+
+optParser = OptionParser.new do |opts|
+  opts.banner = "usage: #{File.basename $0} [options] file1 [file2 ...]" 
+  opts.on('-s', '--step [N]', 'Output information for relaxation step.', 
+                                  "Specify an integer, 'first', 'last', or 'all'", 
+                                  "Default is 'all'") do |s|
+    case s
+    when /([1-9]+)/
+      options[:step] = $1.to_i
+    when "first"
+      options[:step] = :first
+    when "last"
+      options[:step] = :last
+    else
+      options[:step] = :all
+    end
+  end
+
+  opts.on('--debug', 'Debug output') do 
+    options[:debug] = true
+  end
+
+  opts.on('--geometry-delta', 'Display change from input geometry to final geometry') do
+    options[:geometry_delta] = true
+  end
+
+  opts.on('-c', '--self-consistency', 'Output self-consistency information') do
+    options[:self_consistency] = true
+  end
+
+  opts.on('-f', 'Output max force component for each geometry relaxation step') do 
+    options[:forces] = true
+  end
+
+  opts.on('-t', 'Output timings') do
+    options[:timings] = true
+  end
+
+end
+
+begin
+  optParser.parse!(ARGV)
+  
+  files = ARGV
+  if files.empty?
+    puts optParser.help
+    exit
+  end
+  outputs = files.collect{|f|
+    Aims::OutputParser.parse(f)
+  }
+
+  total_sc_iterations = 0
+  total_relaxations = 0
+
+  outputs.each{|output|
+    
+    puts "**************************************************************************"
+    puts "**"
+    puts "**   #{output.original_file}"
+    puts "**"
+    puts "**************************************************************************"
+    
+    steps = case options[:step]
+    when Integer
+      stepno = options[:step]
+      if stepno < 0
+        [output.geometry_steps.last]
+      elsif stepno < output.geometry_steps.size
+        [output.geometry_steps[stepno]]
+      else
+        [output.geometry_steps.last]
+      end
+    when :first
+      [output.geometry_steps.first]
+    when :last
+      [output.geometry_steps.last]
+    else
+      output.geometry_steps
+    end
+    
+    steps.each_with_index{|step, i|
+
+      total_relaxations += 1
+      total_sc_iterations += step.sc_iterations.size
+
+      sciter_format  = "%-20s %20i"
+      timings_format = "%-35s %20.5f"
+      energy_format  = "%-35s %20.5f"
+      force_format  = "%-35s %20.5e"
+      
+      puts "= Relaxation Step #{step.step_num} ="
+      
+      indent = "  "
+      puts indent + sciter_format % ["SC Iterations", step.sc_iterations.size]
+      puts indent + energy_format % ["Total Energy", step.total_energy]
+      puts indent + timings_format % ["Total CPU time", step.total_cpu_time]        
+      puts indent + timings_format % ["Total Wall time", step.total_wall_time]        
+      if options[:forces] and not step.forces.empty?
+        puts indent + force_format % ["Max Force", step.forces.max{|a,b| a.r <=> b.r}.r] 
+      end
+      if options[:timings]
+        puts "  Cumulative SC Timings:"
+        step.timings.each{|t| puts "   " +timings_format % [t[:description], t[:cpu_time]]} 
+      end
+      
+      if options[:self_consistency]
+        
+        indent = "    "
+        
+        # Iterate over each sc iteration
+        step.sc_iterations.each_with_index{|sc_iter, iter|
+          # SC Iteration Header
+          puts "  == SC Iteration #{iter} =="
+
+          # Output convergence criterion
+          puts indent + energy_format % ["Change in total energy", sc_iter.d_etot]
+          puts indent + energy_format % ["Change in sum of eigenvalues", sc_iter.d_eev]
+          puts indent + energy_format % ["Change in charge density", sc_iter.d_rho]
+          
+          # Output timings if requested
+          if options[:timings]
+            if sc_iter.timings
+              sc_iter.timings.each{|t|
+                puts indent + timings_format % [t[:description], t[:cpu_time]]
+              } 
+            else
+              puts "No timing data available."
+            end
+          end
+          puts ""
+        }
+      end
+
+      puts "\n\n"
+      
+      
+    }
+
+    unless output.geometry_converged
+      puts "Warning Geometry not converged!"
+    end
+
+    if options[:geometry_delta]
+      puts "= Change in atomic positions for calculation"
+      puts output.geometry_steps.last.geometry.delta(output.geometry_steps.first.geometry)
+    end
+  }
+
+
+
+  # puts "Total relaxation steps: #{total_relaxations}"
+  # puts "Total sc iterations: #{total_sc_iterations}"
+
+rescue
+  puts ""
+  puts "Sorry. There was an error parsing the remainder of the file."
+  if options[:debug]
+    puts $!.message 
+    puts $!.backtrace
+  else
+    puts "Rerun with --debug for more info"
+  end
+  puts ""
+  exit
+end
+

data/bin/aims_summary.rb

@@ -0,0 +1,28 @@
+#!/usr/bin/env ruby
+
+require 'aims'
+files = ARGV
+if files.empty?
+  puts "usage: #{File.basename $0} file1 [file2] ..."
+  exit
+end
+
+STDOUT.sync = true
+puts "%-10s \t %-20s \t %-15s \t %9s \t %7s \t %10s \t %12s \t %8s \t %10s" % %w(RUN FILE TOTAL_ENERGY NUM_ATOMS K-GRID CONVERGED RELAX_STEPS SC_ITERS TOTAL_TIME)
+format = "%-10s \t %-20s \t %+15e \t %9i \t %7s \t %10s \t %12i \t %8i \t %10.2f"
+files.each{|f|
+  run = f.split(".").last
+  begin
+    o = Aims::OutputParser.parse(f)
+    puts format % [run, f[0...20], 
+                   (o.total_energy.nan? ? Float::NAN : o.total_energy), 
+                   (o.n_atoms or -1), 
+                   (o.k_grid ? o.k_grid.squeeze : "-"), 
+                   o.geometry_converged, 
+                   (o.n_relaxation_steps or -1), 
+                   (o.n_sc_iterations or -1),
+                   o.total_cpu_time]
+  rescue 
+    puts [run, f, "***ERROR***", $!.message].join("\t")
+  end
+}

data/lib/aims.rb

@@ -0,0 +1,35 @@
+# The Aims RubyGem is distributed under the MIT license 
+#
+# Copyright (c) 2012 Joshua Shapiro
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy of this
+# software and associated documentation files (the "Software"), to deal in the Software
+# without restriction, including without limitation the rights to use, copy, modify,
+# merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to the following
+# conditions:
+# 
+# The above copyright notice and this permission notice shall be included in all copies 
+# or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+# INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+# PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
+# FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+# OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+# DEALINGS IN THE SOFTWARE.
+
+require 'aims/vectorize.rb'
+require 'aims/atom.rb'
+require 'aims/bond.rb'
+require 'aims/geometry_parser.rb'
+require 'aims/output.rb'
+require 'aims/plane.rb'
+require 'aims/geometry.rb'
+require 'aims/volume.rb'
+require 'aims/wurtzite.rb'
+require 'aims/zinc_blende.rb'
+
+# :include:README.rdoc
+module Aims
+end

data/lib/aims/atom.rb

@@ -0,0 +1,197 @@
+module Aims
+  
+  class Atom
+    # The last id assigned to an atom
+    @@lastid = 0
+
+    # The x coordinate of the atom in angstrom
+    attr_accessor :x
+    # The y coordinate of the atom in angstrom
+    attr_accessor :y
+    # The z coordinate of the atom in angstrom
+    attr_accessor :z
+    # The +id+ of this atom. Every atom has a unique id
+    attr_accessor :id
+    # The species of this atom
+    attr_accessor :species
+    # The relaxation constraints of this atom
+    attr_accessor :constrain
+    # Two atoms are equal if their coordinates are the same to this precision
+    attr_accessor :precision
+    
+    include Enumerable
+    
+    # Create an atom of the specified species at the given coordinates
+    # * +x+ The x coordinate of the atom in angstrom
+    # * +y+ The y coordinate of the atom in angstrom
+    # * +z+ The z coordinate of the atom in angstrom
+    # * +s+ The atomic species ex. "C", "Si", "S", etc. (can be nil)
+    # * +c+ The relaxation constraints. valid values are TRUE, FALSE, ".true.", ".false.", "x", "y", "z" or %w(x y z)
+    def initialize(x=nil, y=nil, z=nil, s=nil, c=Array.new)
+      self.x = x
+      self.y = y
+      self.z = z
+      self.species = s
+      self.precision = 0.0001
+      self.id = (@@lastid +=1)
+      self.constrain = c
+    end
+    
+    # A boolean value, 
+    # True if the atom has relaxation constraints
+    def constrained?
+      if self.constrain
+        if self.constrain == true
+          true
+        elsif self.constrain.is_a? String
+          true
+        elsif self.constrain.is_a? Array and not self.constrain.empty?
+          true
+        else
+          false
+        end
+      else
+        false
+      end
+    end
+    
+  # Two atoms are equal if their coordinates are equal and they are the same species
+	def ==(atom)
+		((self.x-atom.x).abs < self.precision) & 
+		((self.y-atom.y).abs < self.precision) & 
+		((self.z-atom.z).abs < self.precision) & 
+		(self.species == atom.species)
+	end
+  alias_method :eql?, :==
+    
+  # Implementation for Hash equality testing
+  def hash
+    (self.x*self.y + self.z).abs.ceil
+  end
+  
+  # Enumerate over each coordinate (x,y,z)
+  def each
+    [self.x, self.y, self.z].each{|i| yield i}
+  end
+    
+  # Index into the Atom's coordinates (x,y,z)
+  def [](i)
+    case i
+    when 0
+      self.x
+    when 1
+      self.y
+    when 2
+      self.z
+    else
+      raise "Index Out of Bounds"
+    end
+  end
+    
+  # Return the distance to another atom
+	def distance_to(atom)
+		Math.sqrt((self.x - atom.x)**2 + (self.y - atom.y)**2 + (self.z - atom.z)**2)
+	end
+	
+	# A deep copy of the atom
+    def copy
+      Atom.new(self.x, self.y, self.z, self.species, self.constrain)
+    end
+    
+    # Return a new atom with the same species and relaxation constraints
+    # but with coordinates displaced by +x+, +y+, +z+
+    def displace(x,y,z)
+      Atom.new(self.x+x, self.y+y, self.z+z, self.species, self.constrain)
+    end
+
+    # Displace this atom in place
+    def displace!(x,y,z)
+      self.x += x
+      self.y += y
+      self.z += z
+    end
+
+    # Return an atom rotated about the z-axis using the origin as the center-point.
+    # * +angle+ Is the amount to rotate in degrees (or it can respond to :sin and :cos) 
+    def rotate_Z(angle)
+      sinA = if angle.respond_to? :sin
+        angle.sine
+      else
+        Math.sin(angle*Math::PI/180)
+      end
+      cosA = if angle.respond_to? :cos
+        angle.cos
+      else
+        Math.cos(angle*Math::PI/180)
+      end
+      
+      mat = Matrix[[cosA, -1*sinA, 0],[sinA, cosA, 0], [0,0,1]]
+      rotate(mat) 
+    end
+    
+    # Return an atom rotated about the x-axis using the origin as the center-point.
+    # * +angle+ Is the amount to rotate in degrees (or it can respond to :sin and :cos) 
+    def rotate_X(angle)
+      sinA = if angle.respond_to? :sin
+        angle.sine
+      else
+        Math.sin(angle*Math::PI/180)
+      end
+      cosA = if angle.respond_to? :cos
+        angle.cos
+      else
+        Math.cos(angle*Math::PI/180)
+      end
+      mat = Matrix[[1, 0, 0], [0, cosA, -1*sinA],[0, sinA, cosA]]
+      rotate(mat)       
+    end
+    
+    # Return an atom rotated about the y-axis using the origin as the center-point.
+    # * +angle+ Is the amount to rotate in degrees (or it can respond to :sin and :cos) 
+    def rotate_Y(angle)
+      sinA = if angle.respond_to? :sin
+        angle.sine
+      else
+        Math.sin(angle*Math::PI/180)
+      end
+      cosA = if angle.respond_to? :cos
+        angle.cos
+      else
+        Math.cos(angle*Math::PI/180)
+      end
+      mat = Matrix[[cosA, 0, -1*sinA],[0, 1, 0], [sinA, 0, cosA]]
+      rotate(mat)             
+    end
+
+    # Return a new rotated atom about the origin using the given 3x3 Math::Matrix.
+    def rotate(mat)
+      v = Vector[self.x, self.y, self.z]
+      newv = mat*v
+      Atom.new(newv[0], newv[1], newv[2], self.species, self.constrain)
+    end
+    
+    # Print a string representation of this atom
+    def to_s
+      "%s %16.6f %16.6f %16.6f" % [self.species, self.x, self.y, self.z]
+    end
+    
+    # Print a string representation of this atom formatted in the 
+    # geometry.in format used by Aims
+    def format_geometry_in
+      line = "atom %16.6f %16.6f %16.6f %s" % [self.x, self.y, self.z, self.species]
+      if self.constrain
+        if self.constrain == true
+          line << "\nconstrain_relaxation .true."
+        elsif self.constrain.is_a? String
+          line << "\nconstrain_relaxation #{self.constrain}"
+        elsif self.constrain.is_a? Array and not self.constrain.empty?
+          self.constrain.each{|c|
+            line << "\nconstrain_relaxation #{c}"            
+          }
+          line << "\n"
+        end
+      end
+      line
+    end
+  end
+end