view release on metacpan or  search on metacpan

lib/DateTime/Indic/Chandramana.pm  view on Meta::CPAN

package DateTime::Indic::Chandramana;

# $Id$

use warnings;
use strict;
use Carp qw/ carp croak /;
use DateTime::Indic::Utils qw/ epoch sidereal_year sidereal_month
  lunar_on_or_before newmoon saura_rashi saura_varsha solar_longitude
  tithi_at_dt
  /;
use DateTime::Event::Sunrise;
use DateTime::Util::Calc qw/ amod dt_from_moment mod search_next /;
use Params::Validate qw/ validate BOOLEAN SCALAR OBJECT UNDEF /;
use POSIX qw/ floor /;

=head1 NAME

DateTime::Indic::Chandramana - Base class for Indian luni-solar calendars

=head1 VERSION

Version 0.2

=cut

our $VERSION = '0.2';

=head1 SYNOPSIS

This class is meant to be subclassed not used directly.

=head1 ABSTRACT

A module that implements an Indian chandramAna (luni-solar,) nirAyana 
(sidereal,) khagolasiddha (heliocentric,) and spaShTa (based on the true times 
of astronomical events) calendar.  The calendar described in this module isn't 
actually used as-is though; rather it is a basis for actual Indian luni-solar 
calendars which are implemented in other modules in the L<DateTime::Indic> 
collection.

=cut

my @varsha_nama = qw{ prabhava vibhava shukla pramoda prajApati a~ngirA
  shrImukha bhAva yuvA dhAtA ishvara bahudhAnya pramAthI vikrama vR^isha
  chitrabhAnu subhAnu tAraNa pArthiva vyaya sarvajit sarvadhArI virodhI
  vikrti khara nandana vijaya jaya manmatha durmukha hemalambi vilambi
  vikArI shArvarI plava shubhakrta shobhana krodhI vishvavAsu parAbhava
  plava~nga kIlaka saumya sAdharaNa virodhakrta paridhAvi pramAdi Ananda
  rAkshasa anala pi~Ngala kAlayukta siddhArthi raudra durmati dundubhi
  rudhirodgArI raktAkShI krodhana kshaya
};

my @vara_nama = qw{
  ravivAra somavAra ma~ngalavAra budhavAra guruvAra shukravAra shanivAra
};

my @vara_abbrev = qw { ra so ma bu gu shu sha };

my @masa_nama = qw{
  chaitra vaishAkha jyeShTa AShADha shrAvaNa bhAdrapada ashvina kArtika
  mArgashIrasa pauSha mAgha phAlguna
};

my @masa_abbrev = qw{
  chai vai jye AshA shrA bhA a kA  mAr pau mA phA
};

my @paksha_nama = qw{shukla kR^iShNa};

my @paksha_abbrev = qw{shu kR^i};

my $adhika_nama = 'adhika';

my $adhika_abbrev = 'a';

my @tithi_nama = qw{
  pratipadA dvitIyA tR^itIya chaturthI paMchamI ShaShTI saptamI aShTamI
  navamI dashamI ekAdashI dvAdashI trayodashI chaturdashI
};

my @tithi_abbrev = qw{
  pra dvi tR^i cha paM Sha sa a na da e dvA tra chada
};

my $amavasya_nama = 'amAvAsyA';

my $amavasya_abbrev = 'a';

my $purnima_nama = 'pUrNimA';

my $purnima_abbrev = 'pU';

=head1 DESCRIPTION

Note:  In this document, Sanskrit words are transliterated using the ITRANS
scheme.

=head2 The Year (varSha)

All chandramAna calendars have as their epoch, the first day of the current 
kali yuga which is equivalent to Friday, January 23, -3101 BC in the proleptic 
Gregorian calendar. sidereal years (the time it takes for the sun to make one
pass through the entire zodiac) and days are counted off from this date to
perform calculations but the actual calendars in use, employ different eras to
number years.

=head2 The Lunar Month (mAsa)

chandramAna calendars consists of 12 lunar months (mAsa). A mAsa is defined as 
one complete phase cycle of the Moon. Some calendars use amAsanta mAsa which 
end on the day of the new moon.  Others use pUrNimAnta mAsa which end on the
day of the full moon.

The Sanskrit names of the mAsa and their approximate correspondence to 
Western months are:

  1  chaitra (March-April)            7  ashvina (September-October)
  2  vaishAkha (April-May)            8  kArtika (October-November)
  3  jyeShTa (May-June)               9  mArgashIrasa (November-December)
  4  AShADha (June-July)              10 pauSha (December-January)
  5  shrAvaNa (July-August)           11 mAgha (January-February)
  6  bhAdrapada (August-September)    12 phAlguna (February-March)

Some calendars start from a mAsa other than chaitra.  Nevertheless chaitra 
would still be considered the "first" month despite not being the first month 
of the year.

=head2 Leap and Omitted mAsa (adhikamAsa and kShayamAsa)

Because 12 mAsa can be a little bit more or less than a sidereal year, it is 
sometimes necessary to add or subtract a mAsa to keep the two synchronized.  
When the Sun spends an entire mAsa without entering another zodiacal sign,
the mAsa is called adhika ("leap") and it has the same name as the following 
month.  Very rarely, when the Sun enters two zodiacal signs in what would have 
been one mAsa, it is kShaya (omitted altogether.)

=head2 Waxing and Waning Halves (pakSha)

Each masa is divided into two halves.  The shuklapakSha ("bright part") is 
when the Moon is waxing, culminating in the full moon.  The kR^iShNapakSha 
("dark half") is when the Moon is waning, culminating in the new moon.
Therefore in a pUrNimAnta mAsa, the kR^ishNapakSha is first, followed by the
shuklapakSha, whereas in an amAsanta mAsa, the shuklapakSha is first, followed
by the kR^iShNapakSha.

=head2 Lunar Day (tithi)

Each pakSha consists of tithis which are equivalent to a 12 degree increments 
of increase or decrease in the phase of the Moon.  The tithis of each pakSha
are named and numbered as follows:

  1  pratipadA ("beginning")
  2  dvitIyA ("2nd")
  3  tR^itIya ("3rd")
  4  chaturthI ("4th")
  5  paMchamI ("5th")
  6  ShaShTI ("6th")
  7  saptamI ("7th")
  8  aShTamI ("8th")
  9  navamI  ("9th")
  10 dashamI ("10th")
  11 ekAdashI ("11th")
  12 dvAdashI ("12th")
  13 trayodashI ("13th")
  14 chaturdashI ("14th")
  15 pUrNimA ("full moon")
  30 amAvasya ("new moon")

The tithi of a particular day is the one that prevails at sunrise on that day.  
(This is called the uditatithi.)

=head2 Leap and Omitted tithi (adhikatithi and kShayatithi)

Because the orbital speed of the Moon is not constant, sometimes a tithi can 
start and end entirely within one day.  In that case it is called a 
kShayatithi and it is omitted from the calendar.  Other times, one tithi 
stretches over two sunrises.  This is called a vR^iddha ("large") tithi.  In 
this case, both days have the same number and name.  The first is prefixed 
adhika or "leap".

=head2 Solar Day (vAra)

The Indian day does not start after midnight but at sunrise.  The period 
from sunrise to sunset is called ahasa ("day") and the period from sunset to 
the next sunrise is called rAtra ("night.") Together they make one ahorAtra or
vAra.  Each vAra has a name in a seven-day cycle. Thr Sanskrit names of the
vAra are:

  1 ravivAra ("day of the Sun" i.e. Sunday)
  2 somavAra ("day of the Moon" i.e. Monday)
  3 ma~ngalavAra ("day of Mars" i.e. Tuesday)
  4 budhavAra ("day of Mercury" i.e. Wednesday)
  5 guruvAra  ("day of Jupiter" i.e. Thursday)
  6 shukravAra ("day of Venus" i.e. Friday)
  7 shanivAra ("day of Saturn" i.e. Saturday)

=head2 Latitude, Longitude, and Avantika

In order to know the correct chandramAna date, you have to know the time of 
sunrise and this varies depending on where on Earth you are.  In this module
we use the modern geospatial coordinate system where the prime meridian passing
through Greenwich is 0 degrees longitude and the equator is 0 degrees latitude.
However traditionally the temple of mahAkAla (Shiva as the embodiment of Time)
in Avantika (modern Ujjain, Madhya Pradesh) was considered the prime meridian.

=head1 METHODS

=head2 DATETIME METHODS

These methods are either required by the L<DateTime> API or copied from it.

=head3 new (%args)

Constructs a new instance of this class.  The following arguments can be given:

=over 4

=item * varsha

The numeric year according to the calender's era.  Defaults to 0.

=item * masa

The mAsa (lunar month) as a number from 1 to 12.  Defaults to 1.  See
L<The Lunar Month (mAsa)> for the month corresponding to each number.

=item * adhikamasa

1 if this is an adhikamAsa (leap month), 0 otherwise.  Defaults to 0.

=item * paksha

1 if this is the kR^iShNapakSha (waning half)  of a mAsa, 0 if it is the
shuklapakSha (waxing half.)  Defaults to 0.

=item * tithi