Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
MoonPhase(3)	      User Contributed Perl Documentation	  MoonPhase(3)

NAME
       Astro::MoonPhase	- Information about the	phase of the Moon

SYNOPSIS
       use Astro::MoonPhase;

	       ( $MoonPhase,
		 $MoonIllum,
		 $MoonAge,
		 $MoonDist,
		 $MoonAng,
		 $SunDist,
		 $SunAng ) = phase($seconds_since_1970);

	       @phases	= phasehunt($seconds_since_1970);

	       ($phase,	@times)	= phaselist($start, $stop);

DESCRIPTION
       MoonPhase calculates information	about the phase	of the moon at a given
       time.

FUNCTIONS
   phase()
	       ( $MoonPhase,
		 $MoonIllum,
		 $MoonAge,
		 $MoonDist,
		 $MoonAng,
		 $SunDist,
		 $SunAng )  = phase($seconds_since_1970);

		 $MoonPhase = phase($seconds_since_1970);

       The argument is the time	for which the phase is requested, expressed as
       a time returned by the "time" function. If $seconds_since_1970 is
       omitted,	it does	"phase(time)".

       Return value in scalar context is $MoonPhase, the terminator phase
       angle as	a percentage of	a full circle (i.e., 0 to 1).

       Return values in	array context:
       $MoonPhase:
	   the terminator phase	angle as a percentage of a full	circle (i.e.,
	   0 to	1)

       $MoonIllum:
	   the illuminated fraction of the Moon's disc

       $MoonAge:
	   the Moon's age in days and fraction

       $MoonDist:
	   the distance	of the Moon from the centre of the Earth

       $MoonAng:
	   the angular diameter	subtended by the Moon as seen by an observer
	   at the centre of the	Earth.

       $SunDist:
	   the distance	from the Sun in	km

       $SunAng:
	   the angular size of Sun in degrees

       Example:

	  ( $MoonPhase,
	    $MoonIllum,
	    $MoonAge,
	    $MoonDist,
	    $MoonAng,
	    $SunDist,
	    $SunAng ) =	phase();

	    print "MoonPhase  =	$MoonPhase\n";
	    print "MoonIllum  =	$MoonIllum\n";
	    print "MoonAge    =	$MoonAge\n";
	    print "MoonDist   =	$MoonDist\n";
	    print "MoonAng    =	$MoonAng\n";
	    print "SunDist    =	$SunDist\n";
	    print "SunAng     =	$SunAng\n";

       could print something like this:

	    MoonPhase  = 0.598939375319023
	    MoonIllum  = 0.906458030827876
	    MoonAge    = 17.6870323368022
	    MoonDist   = 372479.357420033
	    MoonAng    = 0.534682403555093
	    SunDist    = 152078368.820205
	    SunAng     = 0.524434538105092

   phasehunt()
	    @phases = phasehunt($seconds_since_1970);

       Finds time of phases of the moon	which surround the given date.	Five
       phases are found, starting and ending with the new moons	which bound
       the current lunation.

       The argument is the time, expressed as a	time returned by the "time"
       function. If $seconds_since_1970	is omitted, it does "phasehunt(time)".

       Example:

	   @phases = phasehunt();
	   print "New Moon	= ", scalar(localtime($phases[0])), "\n";
	   print "First	quarter	= ", scalar(localtime($phases[1])), "\n";
	   print "Full moon	= ", scalar(localtime($phases[2])), "\n";
	   print "Last quarter	= ", scalar(localtime($phases[3])), "\n";
	   print "New Moon	= ", scalar(localtime($phases[4])), "\n";

       could print something like this:

	   New Moon	 = Wed Jun 24 06:51:47 1998
	   First quarter = Wed Jul  1 21:42:19 1998
	   Full	moon	 = Thu Jul  9 19:02:47 1998
	   Last	quarter	 = Thu Jul 16 18:15:18 1998
	   New Moon	 = Thu Jul 23 16:45:01 1998

   phaselist()
	   ($phase, @times) = phaselist($start,	$stop);

       Finds times of all phases of the	moon which occur on or after $start
       but before $stop.  Both the arguments and the return values are
       expressed as seconds since 1970 (like the "time"	function returns).

       $phase is an integer indicating the phase of the	moon at	$times[0], as
       shown in	this table:

	   0  New Moon
	   1  First quarter
	   2  Full Moon
	   3  Last quarter

       The remaining values in @times indicate subsequent phases of the	moon
       (in ascending order by time).  If there are no phases of	the moon
       between $start and $stop, "phaselist" returns the empty list.

       Example:

	   @name = ("New Moon",	"First quarter", "Full moon", "Last quarter");
	   ($phase, @times) = phaselist($start,	$stop);

	   while (@times) {
	     printf "%-14s= %s\n", $name[$phase], scalar localtime shift @times;
	     $phase = ($phase +	1) % 4;
	   }

       could produce the same output as	the "phasehunt"	example	above (given
       the appropriate start & stop times).

ABOUT THE ALGORITHMS
       The algorithms used in this program to calculate	the positions of Sun
       and Moon	as seen	from the Earth are given in the	book Practical
       Astronomy With  Your  Calculator	 by  Peter  Duffett-Smith,   Second
       Edition,	Cambridge University Press, 1981.  Ignore the word
       "Calculator" in the title;  this	 is  an	 essential  reference  if
       you're  interested  in developing  software  which  calculates
       planetary  positions, orbits, eclipses, and  the	 like.	 If  you're
       interested  in  pursuing	 such programming, you should also obtain:

       Astronomical  Formulae for Calculators by Jean Meeus, Third Edition,
       Willmann-Bell, 1985.  A must-have.

       Planetary  Programs  and	 Tables	 from  -4000  to  +2800	 by  Pierre
       Bretagnon  and Jean-Louis Simon,	Willmann-Bell, 1986.  If you want the
       utmost  (outside	 of  JPL)  accuracy  for  the  planets,	 it's	here.

       Celestial BASIC by Eric Burgess,	Revised	Edition, Sybex,	1985.  Very
       cookbook	oriented, and many of the algorithms are hard to dig  out  of
       the turgid BASIC	code, but you'll probably want it anyway.

       Many of these references	can be obtained	from Willmann-Bell, P.O.  Box
       35025,  Richmond,  VA 23235, USA.  Phone: (804) 320-7016.  In addition
       to their	own publications, they stock most of the standard  references
       for mathematical	and positional astronomy.

LICENCE
       This  program is	in the public domain: "Do what thou wilt shall be the
       whole of	the law".

AUTHORS
       The moontool.c Release 2.0:

	   A Moon for the Sun
	   Designed and	implemented by John Walker in December 1987,
	   revised and updated in February of 1988.

       Initial Perl transcription:

	   Raino Pikkarainen, 1998
	   raino.pikkarainen@saunalahti.fi

       The moontool.c Release 2.4:

	   Major enhancements by Ron Hitchens, 1989

       Revisions:

	   Brett Hamilton  http://simple.be/
	   Bug fix, 2003
	   Second transcription	and bugfixes, 2004

	   Christopher J. Madsen  http://www.cjmweb.net/
	   Added phaselist function, March 2007

perl v5.32.0			  2007-03-21			  MoonPhase(3)

NAME | SYNOPSIS | DESCRIPTION | FUNCTIONS | ABOUT THE ALGORITHMS | LICENCE | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Astro::MoonPhase&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help