mirror/astronomy
1
0
Fork 0
mirror of https://github.com/cosinekitty/astronomy.git synced 2026-05-18 22:01:42 -04:00
Code Issues Packages Projects Releases Wiki Activity

Added stub documentation of all C# public symbols.

Browse Source 
This is just to get build errors to go away.
Will have to come back and flesh out all of the documentation
once I start working on the C# documentation generator.
This commit is contained in:
Don Cross
2019-10-24 22:36:18 -04:00
parent e7ae0288c1
commit eabbd4b628
3 changed files with 295 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@@ -1,2 +1,3 @@
.vscode
.vs
__pycache__

147
generate/template/astronomy.cs
View File

@@ -29,31 +29,118 @@ using System;
namespace CosineKitty
{
/// <summary>
/// The enumeration of celestial bodies supported by Astronomy Engine.
/// </summary>
public enum Body
{
/// <summary>
/// A placeholder value representing an invalid or unknown celestial body.
/// </summary>
Invalid = -1,
/// <summary>
/// The planet Mercury.
/// </summary>
Mercury,
/// <summary>
/// The planet Venus.
/// </summary>
Venus,
/// <summary>
/// The planet Earth. Not allowed for many functions for Earth-based observers.
/// </summary>
Earth,
/// <summary>
/// The planet Mars.
/// </summary>
Mars,
/// <summary>
/// The planet Jupiter.
/// </summary>
Jupiter,
/// <summary>
/// The planet Saturn.
/// </summary>
Saturn,
/// <summary>
/// The planet Uranus.
/// </summary>
Uranus,
/// <summary>
/// The planet Neptune.
/// </summary>
Neptune,
/// <summary>
/// The planet Pluto.
/// </summary>
Pluto,
/// <summary>
/// The Sun.
/// </summary>
Sun,
/// <summary>
/// The Earth's natural satellite, the Moon.
/// </summary>
Moon,
}
/// <summary>
/// A date and time used for astronomical calculations.
/// </summary>
public class AstroTime
{
private static readonly DateTime Origin = new DateTime(2000, 1, 1, 12, 0, 0, DateTimeKind.Utc);
/// <summary>
/// UT1/UTC number of days since noon on January 1, 2000.
/// The floating point number of days of Universal Time since noon UTC January 1, 2000.
/// Astronomy Engine approximates UTC and UT1 as being the same thing, although they are
/// not exactly equivalent; UTC and UT1 can disagree by up to plus or minus 0.9 seconds.
/// This approximation is sufficient for the accuracy requirements of Astronomy Engine.
///
/// Universal Time Coordinate (UTC) is the international standard for legal and civil
/// timekeeping and replaces the older Greenwich Mean Time (GMT) standard.
/// UTC is kept in sync with unpredictable observed changes in the Earth's rotation
/// by occasionally adding leap seconds as needed.
///
/// UT1 is an idealized time scale based on observed rotation of the Earth, which
/// gradually slows down in an unpredictable way over time, due to tidal drag by the Moon and Sun,
/// large scale weather events like hurricanes, and internal seismic and convection effects.
/// Conceptually, UT1 drifts from atomic time continuously and erratically, whereas UTC
/// is adjusted by a scheduled whole number of leap seconds as needed.
///
/// The value in `ut` is appropriate for any calculation involving the Earth's rotation,
/// such as calculating rise/set times, culumination, and anything involving apparent
/// sidereal time.
///
/// Before the era of atomic timekeeping, days based on the Earth's rotation
/// were often known as *mean solar days*.
/// </summary>
public readonly double ut;
/// <summary>
/// Terrestrial Time days since noon on January 1, 2000.
/// </summary>
public readonly double tt;
internal double psi;
internal double eps;
/// <summary>
/// Creates an `AstroTime` object from a Universal Time day value.
/// </summary>
/// <param name="ut">The number of days after the J2000 epoch.</param>
public AstroTime(double ut)
{
this.ut = ut;
@@ -61,29 +148,66 @@ namespace CosineKitty
this.psi = this.eps = double.NaN;
}
/// <summary>
/// Creates an `AstroTime` object from a .NET `DateTime` object.
/// </summary>
/// <param name="d">The date and time to be converted to AstroTime format.</param>
public AstroTime(DateTime d)
: this((d - Origin).TotalDays)
{
}
/// <summary>
/// Converts this object to .NET `DateTime` format.
/// </summary>
/// <returns>a UTC `DateTime` object for this `AstroTime` value.</returns>
public DateTime ToUtcDateTime()
{
return Origin.AddDays(ut).ToUniversalTime();
}
/// <summary>
/// Converts this `AstroTime` to ISO 8601 format, expressed in UTC with millisecond resolution.
/// </summary>
/// <returns>Example: "2019-08-30T17:45:22.763".</returns>
public override string ToString()
{
return ToUtcDateTime().ToString("yyyy-MM-ddThh:mm:ss.fffZ");
}
}
/// <summary>
/// A 3D Cartesian vector whose components are expressed in Astronomical Units (AU).
/// </summary>
public class AstroVector
{
/// <summary>
/// The Cartesian x-coordinate of the vector in AU.
/// </summary>
public readonly double x;
/// <summary>
/// The Cartesian y-coordinate of the vector in AU.
/// </summary>
public readonly double y;
/// <summary>
/// The Cartesian z-coordinate of the vector in AU.
/// </summary>
public readonly double z;
/// <summary>
/// The date and time at which this vector is valid.
/// </summary>
public readonly AstroTime t;
/// <summary>
/// Creates an AstroVector.
/// </summary>
/// <param name="x">A Cartesian x-coordinate expressed in AU.</param>
/// <param name="y">A Cartesian y-coordinate expressed in AU.</param>
/// <param name="z">A Cartesian z-coordinate expressed in AU.</param>
/// <param name="t">The date and time at which this vector is valid.</param>
public AstroVector(double x, double y, double z, AstroTime t)
{
this.x = x;
@@ -93,12 +217,32 @@ namespace CosineKitty
}
}
/// <summary>
/// The location of an observer on (or near) the surface of the Earth.
/// </summary>
public class Observer
{
/// <summary>
/// Geographic latitude in degrees north (positive) or south (negative) of the equator.
/// </summary>
public readonly double Latitude;
/// <summary>
/// Geographic longitude in degrees east (positive) or west (negative) of the prime meridian at Greenwich, England.
/// </summary>
public readonly double Longitude;
/// <summary>
/// The height above (positive) or below (negative) sea level, expressed in meters.
/// </summary>
public readonly double Height;
/// <summary>
/// Creates an Observer object.
/// </summary>
/// <param name="latitude">Geographic latitude in degrees north (positive) or south (negative) of the equator.</param>
/// <param name="longitude">Geographic longitude in degrees east (positive) or west (negative) of the prime meridian at Greenwich, England.</param>
/// <param name="height">The height above (positive) or below (negative) sea level, expressed in meters.</param>
public Observer(double latitude, double longitude, double height)
{
Latitude = latitude;
@@ -107,6 +251,9 @@ namespace CosineKitty
}
}
/// <summary>
/// The wrapper class that holds Astronomy Engine functions.
/// </summary>
public static class Astronomy
{
private static readonly deltat_entry_t[] DT = $ASTRO_DELTA_T();

147
source/csharp/astronomy.cs
View File

@@ -29,31 +29,118 @@ using System;
namespace CosineKitty
{
/// <summary>
/// The enumeration of celestial bodies supported by Astronomy Engine.
/// </summary>
public enum Body
{
/// <summary>
/// A placeholder value representing an invalid or unknown celestial body.
/// </summary>
Invalid = -1,
/// <summary>
/// The planet Mercury.
/// </summary>
Mercury,
/// <summary>
/// The planet Venus.
/// </summary>
Venus,
/// <summary>
/// The planet Earth. Not allowed for many functions for Earth-based observers.
/// </summary>
Earth,
/// <summary>
/// The planet Mars.
/// </summary>
Mars,
/// <summary>
/// The planet Jupiter.
/// </summary>
Jupiter,
/// <summary>
/// The planet Saturn.
/// </summary>
Saturn,
/// <summary>
/// The planet Uranus.
/// </summary>
Uranus,
/// <summary>
/// The planet Neptune.
/// </summary>
Neptune,
/// <summary>
/// The planet Pluto.
/// </summary>
Pluto,
/// <summary>
/// The Sun.
/// </summary>
Sun,
/// <summary>
/// The Earth's natural satellite, the Moon.
/// </summary>
Moon,
}
/// <summary>
/// A date and time used for astronomical calculations.
/// </summary>
public class AstroTime
{
private static readonly DateTime Origin = new DateTime(2000, 1, 1, 12, 0, 0, DateTimeKind.Utc);
/// <summary>
/// UT1/UTC number of days since noon on January 1, 2000.
/// The floating point number of days of Universal Time since noon UTC January 1, 2000.
/// Astronomy Engine approximates UTC and UT1 as being the same thing, although they are
/// not exactly equivalent; UTC and UT1 can disagree by up to plus or minus 0.9 seconds.
/// This approximation is sufficient for the accuracy requirements of Astronomy Engine.
///
/// Universal Time Coordinate (UTC) is the international standard for legal and civil
/// timekeeping and replaces the older Greenwich Mean Time (GMT) standard.
/// UTC is kept in sync with unpredictable observed changes in the Earth's rotation
/// by occasionally adding leap seconds as needed.
///
/// UT1 is an idealized time scale based on observed rotation of the Earth, which
/// gradually slows down in an unpredictable way over time, due to tidal drag by the Moon and Sun,
/// large scale weather events like hurricanes, and internal seismic and convection effects.
/// Conceptually, UT1 drifts from atomic time continuously and erratically, whereas UTC
/// is adjusted by a scheduled whole number of leap seconds as needed.
///
/// The value in `ut` is appropriate for any calculation involving the Earth's rotation,
/// such as calculating rise/set times, culumination, and anything involving apparent
/// sidereal time.
///
/// Before the era of atomic timekeeping, days based on the Earth's rotation
/// were often known as *mean solar days*.
/// </summary>
public readonly double ut;
/// <summary>
/// Terrestrial Time days since noon on January 1, 2000.
/// </summary>
public readonly double tt;
internal double psi;
internal double eps;
/// <summary>
/// Creates an `AstroTime` object from a Universal Time day value.
/// </summary>
/// <param name="ut">The number of days after the J2000 epoch.</param>
public AstroTime(double ut)
{
this.ut = ut;
@@ -61,29 +148,66 @@ namespace CosineKitty
this.psi = this.eps = double.NaN;
}
/// <summary>
/// Creates an `AstroTime` object from a .NET `DateTime` object.
/// </summary>
/// <param name="d">The date and time to be converted to AstroTime format.</param>
public AstroTime(DateTime d)
: this((d - Origin).TotalDays)
{
}
/// <summary>
/// Converts this object to .NET `DateTime` format.
/// </summary>
/// <returns>a UTC `DateTime` object for this `AstroTime` value.</returns>
public DateTime ToUtcDateTime()
{
return Origin.AddDays(ut).ToUniversalTime();
}
/// <summary>
/// Converts this `AstroTime` to ISO 8601 format, expressed in UTC with millisecond resolution.
/// </summary>
/// <returns>Example: "2019-08-30T17:45:22.763".</returns>
public override string ToString()
{
return ToUtcDateTime().ToString("yyyy-MM-ddThh:mm:ss.fffZ");
}
}
/// <summary>
/// A 3D Cartesian vector whose components are expressed in Astronomical Units (AU).
/// </summary>
public class AstroVector
{
/// <summary>
/// The Cartesian x-coordinate of the vector in AU.
/// </summary>
public readonly double x;
/// <summary>
/// The Cartesian y-coordinate of the vector in AU.
/// </summary>
public readonly double y;
/// <summary>
/// The Cartesian z-coordinate of the vector in AU.
/// </summary>
public readonly double z;
/// <summary>
/// The date and time at which this vector is valid.
/// </summary>
public readonly AstroTime t;
/// <summary>
/// Creates an AstroVector.
/// </summary>
/// <param name="x">A Cartesian x-coordinate expressed in AU.</param>
/// <param name="y">A Cartesian y-coordinate expressed in AU.</param>
/// <param name="z">A Cartesian z-coordinate expressed in AU.</param>
/// <param name="t">The date and time at which this vector is valid.</param>
public AstroVector(double x, double y, double z, AstroTime t)
{
this.x = x;
@@ -93,12 +217,32 @@ namespace CosineKitty
}
}
/// <summary>
/// The location of an observer on (or near) the surface of the Earth.
/// </summary>
public class Observer
{
/// <summary>
/// Geographic latitude in degrees north (positive) or south (negative) of the equator.
/// </summary>
public readonly double Latitude;
/// <summary>
/// Geographic longitude in degrees east (positive) or west (negative) of the prime meridian at Greenwich, England.
/// </summary>
public readonly double Longitude;
/// <summary>
/// The height above (positive) or below (negative) sea level, expressed in meters.
/// </summary>
public readonly double Height;
/// <summary>
/// Creates an Observer object.
/// </summary>
/// <param name="latitude">Geographic latitude in degrees north (positive) or south (negative) of the equator.</param>
/// <param name="longitude">Geographic longitude in degrees east (positive) or west (negative) of the prime meridian at Greenwich, England.</param>
/// <param name="height">The height above (positive) or below (negative) sea level, expressed in meters.</param>
public Observer(double latitude, double longitude, double height)
{
Latitude = latitude;
@@ -107,6 +251,9 @@ namespace CosineKitty
}
}
/// <summary>
/// The wrapper class that holds Astronomy Engine functions.
/// </summary>
public static class Astronomy
{
private static readonly deltat_entry_t[] DT = new deltat_entry_t[] {