README.rst 3.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136
  1. jdcal
  2. =====
  3. .. _TPM: http://www.sal.wisc.edu/~jwp/astro/tpm/tpm.html
  4. .. _Jeffrey W. Percival: http://www.sal.wisc.edu/~jwp/
  5. .. _IAU SOFA: http://www.iausofa.org/
  6. .. _pip: http://pypi.python.org/pypi/pip
  7. .. _easy_install: packages.python.org/distribute/easy_install.html
  8. This module contains functions for converting between Julian dates and
  9. calendar dates.
  10. A function for converting Gregorian calendar dates to Julian dates, and
  11. another function for converting Julian calendar dates to Julian dates
  12. are defined. Two functions for the reverse calculations are also
  13. defined.
  14. Different regions of the world switched to Gregorian calendar from
  15. Julian calendar on different dates. Having separate functions for Julian
  16. and Gregorian calendars allow maximum flexibility in choosing the
  17. relevant calendar.
  18. Julian dates are stored in two floating point numbers (double). Julian
  19. dates, and Modified Julian dates, are large numbers. If only one number
  20. is used, then the precision of the time stored is limited. Using two
  21. numbers, time can be split in a manner that will allow maximum
  22. precision. For example, the first number could be the Julian date for
  23. the beginning of a day and the second number could be the fractional
  24. day. Calculations that need the latter part can now work with maximum
  25. precision.
  26. All the above functions are "proleptic". This means that they work for
  27. dates on which the concerned calendar is not valid. For example,
  28. Gregorian calendar was not used prior to around October 1582.
  29. A function to test if a given Gregorian calendar year is a leap year is
  30. also defined.
  31. Zero point of Modified Julian Date (MJD) and the MJD of 2000/1/1
  32. 12:00:00 are also given as module level constants.
  33. Examples
  34. --------
  35. Some examples are given below. For more information see
  36. http://oneau.wordpress.com/jdcal/.
  37. Gregorian calendar::
  38. >>> gcal2jd(2000,1,1)
  39. (2400000.5, 51544.0)
  40. >>> 2400000.5 + 51544.0 + 0.5
  41. 2451545.0
  42. >>> gcal2jd(2000,2,30)
  43. (2400000.5, 51604.0)
  44. >>> gcal2jd(2000,3,1)
  45. (2400000.5, 51604.0)
  46. >>> gcal2jd(2001,2,30)
  47. (2400000.5, 51970.0)
  48. >>> gcal2jd(2001,3,2)
  49. (2400000.5, 51970.0)
  50. >>> jd2gcal(*gcal2jd(2000,1,1))
  51. (2000, 1, 1, 0.0)
  52. >>> jd2gcal(*gcal2jd(1950,1,1))
  53. (1950, 1, 1, 0.0)
  54. >>> gcal2jd(2000,1,1)
  55. (2400000.5, 51544.0)
  56. >>> jd2gcal(2400000.5, 51544.0)
  57. (2000, 1, 1, 0.0)
  58. >>> jd2gcal(2400000.5, 51544.5)
  59. (2000, 1, 1, 0.5)
  60. >>> jd2gcal(2400000.5, 51544.245)
  61. (2000, 1, 1, 0.24500000000261934)
  62. >>> jd2gcal(2400000.5, 51544.1)
  63. (2000, 1, 1, 0.099999999998544808)
  64. >>> jd2gcal(2400000.5, 51544.75)
  65. (2000, 1, 1, 0.75)
  66. Julian calendar::
  67. >>> jd2jcal(*jcal2jd(2000, 1, 1))
  68. (2000, 1, 1, 0.0)
  69. >>> jd2jcal(*jcal2jd(-4000, 10, 11))
  70. (-4000, 10, 11, 0.0)
  71. Gregorian leap year::
  72. >>> is_leap(2000)
  73. True
  74. >>> is_leap(2100)
  75. False
  76. JD for zero point of MJD, and MJD for JD2000.0::
  77. >>> print MJD_0
  78. 2400000.5
  79. >>> print MJD_JD2000
  80. 51544.5
  81. Installation
  82. ------------
  83. The module can be installed using `pip`_ or `easy_install`_::
  84. $ pip install jdcal
  85. or,
  86. ::
  87. $ easy_install jdcal
  88. Credits
  89. --------
  90. 1. A good amount of the code is based on the excellent `TPM`_ C library
  91. by `Jeffrey W. Percival`_. A Python interface to this C library is
  92. available at http://github.com/phn/pytpm.
  93. 2. The inspiration to split Julian dates into two numbers came from the
  94. `IAU SOFA`_ C library. No code or algorithm from the SOFA library is
  95. used in `jdcal`.
  96. License
  97. -------
  98. Released under BSD; see
  99. http://www.opensource.org/licenses/bsd-license.php.
  100. For comments and suggestions, email to user `prasanthhn` in the `gmail.com`
  101. domain.