/ 
DateTime-Indic-0.2
River stage zero No dependents
/ DateTime::Indic::Chandramana

NAME

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

VERSION

Version 0.2

SYNOPSIS

This class is meant to be subclassed not used directly.

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 DateTime::Indic collection.

DESCRIPTION

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

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.

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.

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.)

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.

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.)

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".

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)

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.

METHODS

DATETIME METHODS

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

new (%args)

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

  • varsha

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

  • masa

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

  • adhikamasa

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

  • paksha

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

  • tithi

    The numeric tithi (lunar day) expressed as a number from 1 to 14 or by convention, 15 for the pUrNimA (full moon) and 30 for the amAvAsya (new moon.) Defaults to 1.

  • adhikatithi

    1 if this is an adhika (leap) tithi, 0 otherwise. Defaults to 0.

  • latitude

    The latitude of the point for which the date is to be calculated expressed as decimal degrees. Negative values are used for latitudes south of the equator so the allowable range for this argument is from -180 to 180. Defaults to 23.15, the latitude of avantika.

  • longitude

    The longitude of the point for which the panchanga is to be calculated expressed as decimal degrees. Negative values are used for longitudes west of Greenwich so the allowable range for this argument is from -180 to 180. Defaults to 75.76, the longitude of avantika.

  • time_zone

    Time zone for which the panchanga is to be calculated. It can either be a timezone name accepted by DateTime::TimeZone or a DateTime::TimeZone object. Defaults to 'Asia/Kolkata' (Indian Standard Time.)

clone

Returns a copy of the object.

from_object

Builds a DateTime::Calendar::Chandramana object from another DateTime object. This function takes the following parameters:

  • object

    a DateTime API compatible object. (Basically this means it supports utc_rd_Values.) This parameter is required.

  • latitude

    The latitude of the point for which the date is to be calculated expressed as decimal degrees. Negative values are used for latitudes south of the equator so the allowable range for this argument is from -180 to 180. Defaults to 23.15, the latitude of avantika.

  • longitude

    The longitude of the point for which the panchanga is to be calculated expressed as decimal degrees. Negative values are used for longitudes west of Greenwich so the allowable range for this argument is from -180 to 180. Defaults to 75.76, the longitude of avantika.

strftime(@formats)

This function takes one or more parameters consisting of strings containing special specifiers. For each such string it will return a string formatted according to the specifiers, er, specified. The following specifiers are allowed in the format string:

Any method name may be specified using the format %{method} name where "method" is a valid DateTime::Calendar::Chandramana object method.

utc_rd_values

Returns a three-element array containing the current UTC RD days, seconds, and nanoseconds. See DateTime for more details.

UNITS OF TIME

These methods return various parts of a chandramAna date.

varsha

Returns the varSha.

adhikamasa

Returns 1 if this is an adhikamAsa or 0 if it is not.

adhikamasa_abbrev

Returns the abbreviated adhikamAsa name. (By default 'a '.)

adhikamasa_name

Returns the full adhikamAsa name. (By default 'adhika '.)

masa

Returns the mAsa as a number from 1 (chaitra) to 12

masa_abbrev

Returns the abbreviated mAsa name.

masa_name

Returns the full mAsa name.

paksha

Returns 1 if this is the kR^iShNapakSha or 0 if it is the shuklapakSha.

paksha_abbrev

Returns the abbreviated pakSha name. By default either 'shu' for shukla or 'kR^i' for kR^iShNa.

paksha_name

Returns the full paksha name. By default either shukla or kR^iShNa.

adhikatithi

Returns 1 if this is an adhikatithi or 0 if it is not.

adhikatithi_abbrev

Returns the abbreviated adhikatithi name. (By default 'a '.)

adhikatithi_name

Returns the full adhikatithi name. (By default 'adhika '.)

tithi

Returns the tithi as a decimal number.

tithi_abbrev

Returns the abbreviated tithi name.

tithi_name

Returns the full tithi name.

vara

Returns the vAra as a number from 1 (ravivAra) to 7.

vara_abbrev

Returns the abbreviated vAra name.

vara_name

Returns the full vAra name.

BUGS

Please report any bugs or feature requests through the web interface at https://github.com/jaldhar/panchanga/issues. I will be notified, and then you’ll automatically be notified of progress on your bug as I make changes. Please do not use rt.cpan.org!.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc DateTime::Indic::Chandramana

Support requests for this module and questions about panchanga ganita should be sent to the panchanga-devel@lists.braincells.com email list. See http://lists.braincells.com/ for more details.

Questions related to the DateTime API should be sent to the datetime@perl.org email list. See http://lists.perl.org/ for more details.

You can also look for information at:

SEE ALSO

DateTime

AUTHOR

Jaldhar H. Vyas, <jaldhar at braincells.com>

COPYRIGHT AND LICENSE

Copyright (C) 2009, Consolidated Braincells Inc.

This program is free software; you can redistribute it and/or modify it under the terms of either:

  • the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version, or

  • the Artistic License version 2.0.

The full text of the license can be found in the LICENSE file included with this distribution.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 998:

Non-ASCII character seen before =encoding in 'you’ll'. Assuming UTF-8