sun 0.1.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 62b638fc2309bc08dff55796cee15932fd4d791d
-  data.tar.gz: c6c556fafabec3ea2d959d1c2c13c80299d15836
+  metadata.gz: 981419de39da6b66ce62873498c91aee04386fa0
+  data.tar.gz: 0232e38b4729004f092cfb1cb40e724c4167d3cb
 SHA512:
-  metadata.gz: 0b8411da7c981e71efb2584e05278c7f001bb3ca069feb5281dcb7af8782b58d5f7d2ff83f7156ed14a2eb29c0412f8e91e789fbe3d6aaa9283a3637f54539ae
-  data.tar.gz: 7747c1543b1769044b0430c7ed6257b88f4d903eb688e04aed82bc5521c3b016e2bdc3e6e942cf6ac77832b1d17473160273b5ce3fe187572d152883bf9a8b2c
+  metadata.gz: 01e62ce25b8f19b34c9be095521bb76c91cc534a5323154705b4ea0e3792f9bb6d9367369512f4cf292c0f37cf34de38ec7283fd6e671a0db27990b1c7be818f
+  data.tar.gz: 5845f933f5011c81a0089cb9f38eeff5862497c1d70b42fbd2cb58474a4fc2c771b19af6d7842d87b724576fa74a0166d72d67db8380e0ca0b010cd77e5b0094

data/.gitignore

@@ -1,9 +1,6 @@
-/.bundle/
-/.yardoc
-/Gemfile.lock
-/_yardoc/
-/coverage/
-/doc/
-/pkg/
-/spec/reports/
-/tmp/
+.bundle
+.ruby-version
+Gemfile.lock
+coverage
+pkg
+tmp

data/README.md

@@ -1,8 +1,16 @@
-# sun
+# Sun
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/sun`. To experiment with that code, run `bin/consune` for an interactive prompt.
+**Sunrise / sunset times for Ruby**
 
-TODO: Delete this and the text above, and describe your gem
+* [Source Code]
+* [API documentation]
+* [Rubygem]
+
+[Source Code]: https://github.com/allspiritseve/sun "Source code at Github"
+[API documentation]: http://rubydoc.info/gems/sun/frames "RDoc API Documentation at RubyDoc.info"
+[Rubygem]: http://rubygems.org/gems/sun "Ruby gem at RubyGems.org"
+
+Sun is a solar calculator for Ruby based on the [National Oceanic & Atmospheric Administration (NOAA) solar calculator](http://www.esrl.noaa.gov/gmd/grad/solcalc/). Sunrise and sunset results are apparent times and not actual times (due to atmospheric refraction, apparent sunrise occurs shortly before the sun crosses above the horizon and apparent sunset occurs shortly after the sun crosses below the horizon).
 
 ## Installation
 
@@ -22,20 +30,46 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+```ruby
+time = Time.new(2015, 1, 1, 12, 0, 0, '-05:00')
+latitude = 40.75
+longitude = -73.99
 
-## Development
+# Sunrise
+Sun.sunrise(time, latitude, longitude) # => 2015-01-01 07:20:02 -0500
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/consune` for an interactive prompt that will allow you to experiment.
+# Solar noon
+Sun.solar_noon(time, latitude, longitude) # => 2015-01-01 11:59:09 -0500
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+# Sunset
+Sun.sunset(time, latitude, longitude) # => 2015-01-01 16:38:16 -0500
 
-## Contributing
+# Sunrise in minutes after midnight (UTC)
+Sun.sunrise_minutes(time, latitude, longitude) # => 740.0366212342198
+
+# Solar noon in minutes after midnight (UTC)
+Sun.solar_noon(time, latitude, longitude) # => 1019.1596410575343
+
+# Sunset in minutes after midnight (UTC)
+Sun.sunset(time, latitude, longitude) # => 1298.2826608808487
+```
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/sun. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](contributor-covenant.org) code of conduct.
+## Notes
 
+All of the above methods accept Date or Time objects for `time`. If a `Time` object is passed, the calculations will be performed on the return value of [`Time#to_date`](http://ruby-doc.org/stdlib-2.2.2/libdoc/date/rdoc/Time.html#method-i-to_date), which is timezone-dependent (for example, 1am in Michigan is 10pm on the previous day in California). To force calculations on a specific date regardless of timezone, pass a `Date` object.
+
+Sun times are returned as [`Time`](http://ruby-doc.org/core-2.2.2/Time.html) objects in the local system timezone. To convert to a different timezone, you can use [`TZInfo::Timezone#utc_to_local`](http://www.rubydoc.info/gems/tzinfo/TZInfo/Timezone#utc_to_local-instance_method) or [`ActiveSupport::TimeZone#at`](http://api.rubyonrails.org/classes/ActiveSupport/TimeZone.html#method-i-at).
+
+## References
+
+* [NOAA Solar Calculation Details](http://www.esrl.noaa.gov/gmd/grad/solcalc/calcdetails.html)
+* [NOAA Solar Calculator](http://www.esrl.noaa.gov/gmd/grad/solcalc/)
+* [Wikipedia: Sunrise equation](https://en.wikipedia.org/wiki/Sunrise_equation)
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/allspiritseve/sun. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](contributor-covenant.org) code of conduct.
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
-

data/Rakefile

@@ -4,7 +4,7 @@ require "rake/testtask"
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
   t.libs << "lib"
-  t.test_files = FileList['test/**/*_test.rb']
+  t.test_files = FileList['test/*_test.rb']
 end
 
 task :default => :test

data/circle.yml

@@ -0,0 +1,3 @@
+machine:
+  ruby:
+    version: 2.2.2

data/lib/sun.rb

@@ -1,34 +1,67 @@
+require 'date'
 require 'sun/version'
 
 module Sun
+  # The approximate correction for atmospheric refraction at sunrise and sunset
   SOLAR_ZENITH = 90.833
 
-  # Noon on January 1st, 2000
+  # 2000-01-01 12:00:00 UTC in Julian days
   JULIAN_CONSTANT = 2451545.to_r
 
-  # Sun times
-  def self.solar_noon(time, latitude, longitude)
-    minutes = solar_noon_minutes(time, latitude, longitude)
-    date_at_time(time.to_date, minutes)
+  class Error < StandardError
+  end
+
+  class InvalidTime < Error
+  end
+
+  class InvalidCoordinates < Error
   end
 
+  # Sun times (UTC)
+
   def self.sunrise(time, latitude, longitude)
-    minutes = sunrise_minutes(time, latitude, longitude)
-    date_at_time(time.to_date, minutes)
+    sun_time(:sunrise, time, latitude, longitude)
+  end
+
+  def self.solar_noon(time, latitude, longitude)
+    sun_time(:solar_noon, time, latitude, longitude)
   end
 
   def self.sunset(time, latitude, longitude)
-    minutes = sunset_minutes(time, latitude, longitude)
-    date_at_time(time.to_date, minutes)
+    sun_time(:sunset, time, latitude, longitude)
+  end
+
+  # Sun times in minutes after midnight (UTC)
+
+  def self.sunrise_minutes(time, latitude, longitude)
+    sun_time_minutes(:sunrise, time, latitude, longitude)
+  end
+
+  def self.solar_noon_minutes(time, latitude, longitude)
+    sun_time_minutes(:solar_noon, time, latitude, longitude)
+  end
+
+  def self.sunset_minutes(time, latitude, longitude)
+    sun_time_minutes(:sunset, time, latitude, longitude)
   end
 
   # Helpers
+
+  def self.date(time)
+    case time
+    when Date then time
+    when Time then time.to_date
+    else
+      raise InvalidTime, "must pass a Date or Time object"
+    end
+  end
+
   def self.degrees(radians)
-    180.0 * radians / Math::PI
+    Rational(180 * radians, Math::PI)
   end
 
   def self.radians(degrees)
-    Math::PI * degrees / 180.0
+    Rational(Math::PI * degrees, 180)
   end
 
   def self.date_to_unix_time(date)
@@ -36,11 +69,42 @@ module Sun
   end
 
   def self.date_at_time(date, minutes)
-    date_to_unix_time(date) + minutes * 60
+    Time.at(date_to_unix_time(date) + minutes * 60)
+  end
+
+  # Base our calculations off the astronomical julian date for our input time.
+  # Our formula is sensitive to time of day, so we ignore it in order to give
+  # consistent results for any time on the same date.
+  def self.sun_time(type, time, latitude, longitude)
+    date = date(time)
+    minutes = sun_time_minutes(type, date, latitude, longitude)
+    date_at_time(date, minutes)
   end
 
+  def self.sun_time_minutes(type, time, latitude, longitude)
+    date = date(time)
+    offset = offset_multiplier(type) * 4 * hour_angle(date, latitude)
+    720 - (4 * longitude) - equation_of_time(date, longitude) + offset
+  rescue Math::DomainError
+    raise InvalidCoordinates, "Could not determine sun times for coordinates: #{latitude}, #{longitude}"
+  end
+
+  def self.offset_multiplier(type)
+    case type
+    when :sunrise then -1
+    when :solar_noon then 0
+    when :sunset then 1
+    end
+  end
+
+  # Calculations
+
   def self.julian_days(time)
-    time.utc.to_datetime.ajd
+    if time.is_a?(Time)
+      time.to_datetime.ajd
+    else
+      date(time).ajd
+    end
   end
 
   def self.julian_century(time)
@@ -59,9 +123,8 @@ module Sun
     357.52911 + julian_century * (35999.05029 - 0.0001537 * julian_century)
   end
 
-  # MOD(280.46646+G2*(36000.76983 + G2*0.0003032),360)
   def self.geometric_mean_longitude(julian_century)
-    280.46646 + julian_century * (36000.76983 + julian_century * 0.0003032) % 360
+    (280.46646 + julian_century * (36000.76983 + julian_century * 0.0003032)) % 360
   end
 
   def self.y(oblique_correction)
@@ -75,7 +138,6 @@ module Sun
   def self.equation_of_center(julian_century)
     geometric_mean_anomoly = geometric_mean_anomoly(julian_century)
     Math.sin(radians(geometric_mean_anomoly)) * (1.914602 - julian_century * (0.004817 + 0.000014 * julian_century)) + Math.sin(radians(2 * geometric_mean_anomoly)) * (0.019993 - 0.000101 * julian_century) + Math.sin(radians(3 * geometric_mean_anomoly)) * 0.00028
-    # =SIN(RADIANS(J2))*(1.914602-G2*(0.004817+0.000014*G2))+SIN(RADIANS(2*J2))*(0.019993-0.000101*G2)+SIN(RADIANS(3*J2))*0.00028
   end
 
   def self.true_longitude(julian_century)
@@ -90,8 +152,8 @@ module Sun
     degrees(Math.asin(Math.sin(radians(oblique_correction)) * Math.sin(radians(apparent_longitude(julian_century)))))
   end
 
-  def self.equation_of_time(time, longitude)
-    julian_century = julian_century(time)
+  def self.equation_of_time(date, longitude)
+    julian_century = julian_century(date)
     oblique_correction = oblique_correction(julian_century)
     geometric_mean_anomoly = geometric_mean_anomoly(julian_century)
     geometric_mean_longitude = geometric_mean_longitude(julian_century)
@@ -100,22 +162,11 @@ module Sun
     4 * degrees(y * Math.sin(2 * radians(geometric_mean_longitude)) - 2 * eccentricity_of_earth_orbit * Math.sin(radians(geometric_mean_anomoly)) + 4 * eccentricity_of_earth_orbit * y * Math.sin(radians(geometric_mean_anomoly)) * Math.cos(2 * radians(geometric_mean_longitude)) - 0.5 * y * y * Math.sin(4 * radians(geometric_mean_longitude)) - 1.25 * eccentricity_of_earth_orbit * eccentricity_of_earth_orbit * Math.sin(2 * radians(geometric_mean_anomoly)))
   end
 
-  def self.hour_angle(time, latitude)
-    julian_century = julian_century(time)
+  def self.hour_angle(date, latitude)
+    julian_century = julian_century(date)
     oblique_correction = oblique_correction(julian_century)
     declination = declination(oblique_correction, julian_century)
-    degrees(Math.acos(Math.cos(radians(90.833)) / (Math.cos(radians(latitude)) * Math.cos(radians(declination))) - Math.tan(radians(latitude)) * Math.tan(radians(declination))))
-  end
-
-  def self.solar_noon_minutes(time, latitude, longitude)
-    720 - (4 * longitude) - equation_of_time(time, longitude)
-  end
-
-  def self.sunrise_minutes(time, latitude, longitude)
-    solar_noon_minutes(time, latitude, longitude) - 4 * hour_angle(time, latitude)
-  end
-
-  def self.sunset_minutes(time, latitude, longitude)
-    solar_noon_minutes(time, latitude, longitude) + 4 * hour_angle(time, latitude)
+    res = Math.cos(radians(SOLAR_ZENITH)) / (Math.cos(radians(latitude)) * Math.cos(radians(declination))) - Math.tan(radians(latitude)) * Math.tan(radians(declination))
+    degrees(Math.acos(res))
   end
 end

data/lib/sun/version.rb

@@ -1,3 +1,3 @@
 module Sun
-  VERSION = "0.1.1"
+  VERSION = "1.0.0"
 end

data/sun.gemspec

@@ -9,18 +9,10 @@ Gem::Specification.new do |spec|
   spec.authors = ['Cory Kaufman-Schofield']
   spec.email = ['cory@corykaufman.com']
 
-  spec.summary = 'Calculate sunrise and sunset for any place on earth'
+  spec.summary = 'Calculate sunrise and sunset times'
   spec.homepage = 'https://github.com/allspiritseve/sun'
   spec.license = 'MIT'
 
-  # Prevent pushing this gem to RubyGems.org by setting 'allowed_push_host', or
-  # delete this section to allow pushing this gem to any host.
-  if spec.respond_to?(:metadata)
-    spec.metadata['allowed_push_host'] = 'http://mygemserver.com'
-  else
-    raise 'RubyGems 2.0 or newer is required to protect against public gem pushes.'
-  end
-
   spec.files = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^test/}) }
   spec.bindir = 'exe'
   spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
@@ -31,5 +23,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'minitest'
   spec.add_development_dependency 'minitest-reporters'
   spec.add_development_dependency 'rake'
-  spec.add_development_dependency 'tzinfo'
+  spec.add_development_dependency 'simplecov'
 end

metadata

@@ -1,97 +1,97 @@
 --- !ruby/object:Gem::Specification
 name: sun
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Cory Kaufman-Schofield
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-09-04 00:00:00.000000000 Z
+date: 2015-09-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: byebug
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: minitest-reporters
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: tzinfo
+  name: simplecov
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 description: 
@@ -101,8 +101,8 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
-- .travis.yml
+- ".gitignore"
+- ".travis.yml"
 - CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE.txt
@@ -110,32 +110,32 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- circle.yml
 - lib/sun.rb
 - lib/sun/version.rb
 - sun.gemspec
 homepage: https://github.com/allspiritseve/sun
 licenses:
 - MIT
-metadata:
-  allowed_push_host: http://mygemserver.com
+metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.14
+rubygems_version: 2.4.8
 signing_key: 
 specification_version: 4
-summary: Calculate sunrise and sunset for any place on earth
+summary: Calculate sunrise and sunset times
 test_files: []