Loading...
Searching...
No Matches
supernovas::CatalogEntry Class Reference
Astronomical object of interest | Spectroscopic applications

Defines the astrometric parameters of a sidereal source, such as a star, a Galactic cloud, a distant galaxy, or a quasar. More...

`#include <supernovas.h>`

Inheritance diagram for supernovas::CatalogEntry:

## Public Member Functions

| CatalogEntry (cat_entry e, const Equinox &system=Equinox::icrs())
| Instantiates a new catalog entry with a NOVAS C cat_entry data structure and the equatorial coordinate system in which it is defined.
| CatalogEntry (const std::string &name, const Ecliptic &coords)
| Instantiates a new catalog entry with a given name and ecliptic catalog coordinates.
| CatalogEntry (const std::string &name, const Equatorial &coords)
| Instantiates a new catalog entry with a given name and catalog coordinates.
| CatalogEntry (const std::string &name, const Galactic &coords)
| Instantiates a new catalog entry with a given name and galactic catalog coordinates.
const cat_entry * | _cat_entry () const
| Returns a pointer to the underlying NOVAS C cat_entry data structure, for use with the standard C API.
Angle | dec () const
| Returns the catalog declination coordinate as a angle.
Coordinate | distance () const
| Returns the catalog (light-time) distance of the source.
CatalogEntry & | distance (const Coordinate &dist)
| Sets the distance of this source, defined at the same epoch as the catalog coordinates, returning itself to enable builder pattern.
CatalogEntry & | distance (double meters)
| Sets the distance of this source, defined at the same epoch as the catalog coordinates, returning itself to enable builder pattern.
bool | equals (const CatalogEntry &other) const
| Checks if this catalog entry matches another within the standard tolerances.
Equatorial | equatorial () const
| Returns the equatorial catalog coordinates of this source.
std::string | name () const
| Returns the catalog name that was defined.
bool | operator!= (const CatalogEntry &other) const
| Checks if this catalog entry differs from another within.
bool | operator== (const CatalogEntry &other) const
| Checks if this catalog entry matches another within the standard tolerances.
Angle | parallax () const
| Returns the parallax of the source.
CatalogEntry & | parallax (const Angle &angle)
| Sets the parallax this source, defined at the same epoch as the catalog coordinates, returning itself to enable builder pattern.
CatalogEntry & | parallax (double radians)
| Sets the parallax of this source, defined at the same epoch as the catalog coordinates, returning itself to enable builder pattern.
CatalogEntry & | proper_motion (double ra, double dec)
| Sets the proper motion of this source, defined at the same epoch as the catalog coordinates, returning itself to enable builder pattern.
TimeAngle | ra () const
| Returns the catalog right ascension (R.A.) coordinate as a time-angle.
ScalarVelocity | radial_velocity () const
| Returns the barycentric radial velocity of the source, that is the radial velocity with respect to the Solar System Barycenter (SSB).
CatalogEntry & | radial_velocity (const ScalarVelocity &v)
| Sets the radial velocity of this source relative to the Solar System Barycenter (SSB), defined at the same epoch as the catalog coordinates, and returning itself to enable builder pattern.
CatalogEntry & | radial_velocity (double v_ms)
| Sets the radial velocity of this source relative to the Solar System Barycenter (SSB), defined at the same epoch as the catalog coordinates, and returning itself to enable builder pattern.
double | redshift () const
| Returns the barycentric redshift of the source, that is the redshift measure with respect to the Solar System Barycenter (SSB).
CatalogEntry & | redshift (double z)
| Sets the redshift of this source relative to the Solar System Barycenter (SSB), defined at the same epoch as the catalog coordinates, and returning itself to enable builder pattern.
const Equinox & | system () const
| Returns the equatorial coordinate system in which this catalog entry is defined.
CatalogSource | to_source () const
| Returns a new catalog source based created from this catalog entry.
std::string | to_string (int decimals=3) const
| Returns a human-readable string representation of this catalog entry, showing only the most basic data.
ScalarVelocity | v_lsr () const
| Returns the scalar source velocity with respect to the Local Standard of Rest (LSR).
CatalogEntry & | v_lsr (const ScalarVelocity &v)
| Sets the motion of this source relative to the Local Standard of Rest (LSR), defined at the same epoch as the catalog coordinates, and returning itself to enable builder pattern.
CatalogEntry & | v_lsr (double v_ms)
| Sets the motion of this source relative to the Local Standard of Rest (LSR), defined at the same epoch as the catalog coordinates, and returning itself to enable builder pattern.
Public Member Functions inherited from supernovas::Validating
bool | is_valid () const
| Returns the previously set 'valid' state of the implementing instance.
| operator bool () const
| Objects that implement Validating can be used in conditionals directly, without explicitly calling is_valid().

## Additional Inherited Members

Protected Member Functions inherited from supernovas::Validating
| Validating ()
| dummy constructor;
Protected Attributes inherited from supernovas::Validating
bool | _valid = false
| the state variable.

## Detailed Description

Defines the astrometric parameters of a sidereal source, such as a star, a Galactic cloud, a distant galaxy, or a quasar.

NOTES:

1. This class uses a builder pattern to populate the astrometric parameters, bit-by-bit, as needed. You should avoid using the builder functions in a multi-threaded environment. The best practice is to build the catalog entry first, before using an unmodifiable const copy of it in parallel threads.

Since
  1.6

See also
  CatalogSource

## Constructor & Destructor Documentation

## CatalogEntry() [1/4]

supernovas::CatalogEntry::CatalogEntry | ( | const std::string & | name,
|  | const Equatorial & | coords )

Instantiates a new catalog entry with a given name and catalog coordinates.

After instantiation, one may populate additional data using the builder functions of this class, such as:

- radial or LSR velocity, or redshift
- proper motion (if any)
- parallax or distance, if known (by default 1 Gpc is assumed)
- catalog name, and catalog ID number

For example:

CatalogEntry star =
CatalogEntry("Antares", Equatorial("16h26m20.1918s", "-26d19m23.138s", Equinox::b1950()))
.proper_motion( -12.11 * Unit::mas / Unit::year, -23.30 * Unit::mas / Unit::year)
.parallax(5.89 * Unit::arcsec)
.radial_velocity(-3.4 * Unit::km_per_s);
supernovas::CatalogEntry::CatalogEntry
CatalogEntry(const std::string &name, const Equatorial &coords)
Instantiates a new catalog entry with a given name and catalog coordinates.
Definition CatalogEntry.cpp:77
supernovas::Equatorial
Equatorial coordinates (RA, Dec / α, δ), representing the direction on the sky, for a particular type...
Definition supernovas.h:995
supernovas::Equinox::b1950
static const Equinox & b1950()
The system of the dynamical equator at the B1950 epoch (0 UTC, 1 January 1950).
Definition Equinox.cpp:614
supernovas::Unit::arcsec
static constexpr double arcsec
[rad] 1 second or arc in radians
Definition supernovas.h:175
supernovas::Unit::mas
static constexpr double mas
[rad] 1 millisecond of arc in radians
Definition supernovas.h:176
supernovas::Unit::km_per_s
static constexpr double km_per_s
[m/s] 1 kilometer per second in m/s
Definition supernovas.h:155

Parameters

  name | source name. It is treated case insensitively, unless the user calls novas_case_sensitive(true) prior to instantiation. The user may chose any name that is appropriate for their application.
  coords | Catalog coordinates (equatorial)

Since
  1.6

See also
  proper_motion(), parallax(), distance(), radial_velocity(), v_lsr(), redshift(), catalog()

References supernovas::Validating::_valid, supernovas::Equatorial::dec(), supernovas::Angle::deg(), supernovas::TimeAngle::hours(), supernovas::Validating::is_valid(), name(), novas_init_cat_entry(), supernovas::Equatorial::ra(), and system().

Referenced by CatalogEntry(), CatalogEntry(), distance(), distance(), equals(), operator!=(), operator==(), parallax(), parallax(), proper_motion(), radial_velocity(), radial_velocity(), redshift(), v_lsr(), and v_lsr().

## CatalogEntry() [2/4]

supernovas::CatalogEntry::CatalogEntry | ( | const std::string & | name,
|  | const Ecliptic & | coords )

Instantiates a new catalog entry with a given name and ecliptic catalog coordinates.

After instantiation, one may populate additional data using the builder functions of this class, such as:

- radial or LSR velocity, or redshift
- proper motion (if any)
- parallax or distance, if known (by default 1 Gpc is assumed)
- catalog name, and catalog ID number

See CatalogEntry(strd::string&, Equatorial&) for more information on using builder patterns.

Parameters

  name | Source name. It is treated case insensitively, unless the user calls novas_case_sensitive(true) prior to instantiation. The user may chose any name that is appropriate for their application.
  coords | Catalog coordinates (ecliptic)

Since
  1.6

See also
  proper_motion(), parallax(), distance(), radial_velocity(), v_lsr(), redshift(), catalog()

References CatalogEntry(), and name().

## CatalogEntry() [3/4]

supernovas::CatalogEntry::CatalogEntry | ( | const std::string & | name,
|  | const Galactic & | coords )

Instantiates a new catalog entry with a given name and galactic catalog coordinates.

After instantiation, one may populate additional data using the builder functions of this class, such as:

- radial or LSR velocity, or redshift
- proper motion (if any)
- parallax or distance, if known (by default 1 Gpc is assumed)
- catalog name, and catalog ID number

See CatalogEntry(strd::string&, Equatorial&) for more information on using builder patterns.

NOTES:

1. The Galactic coordinate system is somewhat ambigiously defined (see Liu+2011). As a result one should probably avoid using it when high precision is required.

Parameters

  name | Source name. It is treated case insensitively, unless the user calls novas_case_sensitive(true) prior to instantiation. The user may chose any name that is appropriate for their application.
  coords | Catalog coordinates (galactic)

Since
  1.6

See also
  proper_motion(), parallax(), distance(), radial_velocity(), v_lsr(), redshift(), catalog()

References CatalogEntry(), and name().

## CatalogEntry() [4/4]

supernovas::CatalogEntry::CatalogEntry | ( | cat_entry | e,
|  | const Equinox & | system = Equinox::icrs() )

explicit

Instantiates a new catalog entry with a NOVAS C cat_entry data structure and the equatorial coordinate system in which it is defined.

- radial or LSR velocity, or redshift
- proper motion (if any)
- parallax or distance, if known (by default 1 Gpc is assumed)
- catalog name, and catalog ID number

See CatalogEntry(strd::string&, Equatorial&) for more information on using builder patterns.

Parameters

  e | NOVAS C cat_entry data structure (it is not referenced)
  system | the equatorial coordinate system in which the cat_entry data was defined.

Since
  1.6

References system().

## Member Function Documentation

## _cat_entry()

const cat_entry * supernovas::CatalogEntry::_cat_entry | ( |  | ) | const

Returns a pointer to the underlying NOVAS C cat_entry data structure, for use with the standard C API.

Returns
  a pointer to the underlying NOVAS C cat_entry data structure.

Since
  1.6

Referenced by supernovas::CatalogSource::CatalogSource().

## dec()

Angle supernovas::CatalogEntry::dec | ( |  | ) | const

Returns the catalog declination coordinate as a angle.

Returns
  the catalog declination angle as defined in the catalog system.

Since
  1.6

See also
  system(), equatorial()
  ra(), distance(), parallax(), radial_velocity(), v_lsr(), redshift()

References supernovas::Unit::deg, and supernovas::Validating::is_valid().

Referenced by equatorial(), and proper_motion().

## distance() [1/3]

Coordinate supernovas::CatalogEntry::distance | ( |  | ) | const

Returns the catalog (light-time) distance of the source.

Returns
  the distance of the source, or 1 Gpc if it was not explicitly defined.

Since
  1.6

See also
  system(), parallax()
  ra(), dec(), radial_velocity(), v_lsr(), redshift()

References supernovas::Validating::is_valid(), and supernovas::Unit::kpc.

Referenced by distance(), and to_string().

## distance() [2/3]

CatalogEntry & supernovas::CatalogEntry::distance | ( | const Coordinate & | dist | ) |

Sets the distance of this source, defined at the same epoch as the catalog coordinates, returning itself to enable builder pattern.

Parameters

  dist | source (light-time) distance

Returns
  itself

Since
  1.6

See also
  parallax()
  system(), radial_velocity(), v_lsr(), redshift(), proper_motion(), catalog()

References CatalogEntry(), distance(), and supernovas::Coordinate::m().

## distance() [3/3]

CatalogEntry & supernovas::CatalogEntry::distance | ( | double | meters | ) |

Sets the distance of this source, defined at the same epoch as the catalog coordinates, returning itself to enable builder pattern.

Parameters

  meters | [m] source (light-time) distance

Returns
  itself

Since
  1.6

See also
  parallax()
  system(), radial_velocity(), v_lsr(), redshift(), proper_motion(), catalog()

References CatalogEntry(), supernovas::Validating::_valid, novas_set_distance(), and supernovas::Unit::pc.

## equals()

bool supernovas::CatalogEntry::equals | ( | const CatalogEntry & | other | ) | const

Checks if this catalog entry matches another within the standard tolerances.

For two catalog entries to be equals, they must have matching:

- names (case sensitive)
- catalog IDs (case sensitive)
- numerical IDs
- coordinates within 1 μas.
- proper motions to within 1 μas / century.
- parallaxes to within 10-4 % of their geometric mean.
- radial velocities to withing 1 mm/s.

Note, that a catalog entry may not equal itself if it contains NAN or infinite components.

Parameters

  other | the other catalog entry.

Returns
  true if both catalog entries essentially describe the same source, otherwise false.

Since
  1.7

See also
  operator==(), operator!=()

References CatalogEntry(), and novas_equals_cat_entry().

Referenced by operator!=(), and operator==().

## equatorial()

Equatorial supernovas::CatalogEntry::equatorial | ( |  | ) | const

Returns the equatorial catalog coordinates of this source.

Returns
  the equatorial coordinates of the source in the catalog system

Since
  1.6

See also
  system(), ra(), dec(), distance()

References dec(), supernovas::Validating::is_valid(), ra(), and system().

Referenced by to_string().

## name()

std::string supernovas::CatalogEntry::name | ( |  | ) | const

Returns the catalog name that was defined.

Returns
  the given catalog name.

Since
  1.6

See also
  number()

Referenced by CatalogEntry(), CatalogEntry(), CatalogEntry(), and to_string().

## operator!=()

bool supernovas::CatalogEntry::operator!= | ( | const CatalogEntry & | other | ) | const

Checks if this catalog entry differs from another within.

Same as !equals(). See equals() for details of the comparisons performed.

Parameters

  other | the other catalog entry.

Returns
  true if this catalog entry and the argument describe two distinct sources, otherwise false.

Since
  1.7

See also
  equals(), operator!=()

References CatalogEntry(), and equals().

## operator==()

bool supernovas::CatalogEntry::operator== | ( | const CatalogEntry & | other | ) | const

Checks if this catalog entry matches another within the standard tolerances.

See equals() for details.

Parameters

  other | the other catalog entry.

Returns
  true if both catalog entries essentially describe the same source, otherwise false.

Since
  1.7

See also
  equals(), operator!=()

References CatalogEntry(), and equals().

## parallax() [1/3]

Angle supernovas::CatalogEntry::parallax | ( |  | ) | const

Returns the parallax of the source.

Returns
  the parallax of the source, or 1 μas if not explicitly defined.

Since
  1.6

See also
  system(), distance()
  ra(), dec(), radial_velocity(), v_lsr(), redshift()

References supernovas::Validating::is_valid(), and supernovas::Unit::mas.

Referenced by parallax().

## parallax() [2/3]

CatalogEntry & supernovas::CatalogEntry::parallax | ( | const Angle & | angle | ) |

Sets the parallax this source, defined at the same epoch as the catalog coordinates, returning itself to enable builder pattern.

Parameters

  angle | Parallax angle

Returns
  itself

Since
  1.6

See also
  distance()
  system(), radial_velocity(), v_lsr(), redshift(), proper_motion(), catalog()

References CatalogEntry(), parallax(), and supernovas::Angle::rad().

## parallax() [3/3]

CatalogEntry & supernovas::CatalogEntry::parallax | ( | double | radians | ) |

Sets the parallax of this source, defined at the same epoch as the catalog coordinates, returning itself to enable builder pattern.

Parameters

  radians | [rad] Parallax angle

Returns
  itself

Since
  1.6

See also
  distance()
  system(), radial_velocity(), v_lsr(), redshift(), proper_motion(), catalog()

References CatalogEntry(), supernovas::Validating::_valid, supernovas::Unit::mas, and novas_set_parallax().

## proper_motion()

CatalogEntry & supernovas::CatalogEntry::proper_motion | ( | double | ra,
|  | double | dec )

Sets the proper motion of this source, defined at the same epoch as the catalog coordinates, returning itself to enable builder pattern.

Parameters

  ra | [rad/s] Proper motion in the R.A. direction
  dec | [rad/s] Proper motion in the declination direction

Returns
  itself

Since
  1.6

See also
  parallax(), distance(), radial_velocity(), v_lsr(), redshift(), catalog()
  system()

References CatalogEntry(), supernovas::Validating::_valid, dec(), supernovas::Unit::mas, novas_set_proper_motion(), ra(), and supernovas::Unit::yr.

## ra()

TimeAngle supernovas::CatalogEntry::ra | ( |  | ) | const

Returns the catalog right ascension (R.A.) coordinate as a time-angle.

Returns
  the catalog right-ascension angle as defined in the catalog system.

Since
  1.6

See also
  system(), equatorial()
  dec(), distance(), parallax(), radial_velocity(), v_lsr(), redshift()

References supernovas::Unit::hour_angle, and supernovas::Validating::is_valid().

Referenced by equatorial(), and proper_motion().

## radial_velocity() [1/3]

ScalarVelocity supernovas::CatalogEntry::radial_velocity | ( |  | ) | const

Returns the barycentric radial velocity of the source, that is the radial velocity with respect to the Solar System Barycenter (SSB).

Returns
  the barycentric radial velocity (relative the SSB), or 0.0 if the source motion was not explicitly defined.

Since
  1.6

See also
  system(), v_lsr(), redshift()
  ra(), dec(), distance(), parallax()

References supernovas::Validating::is_valid(), and supernovas::Unit::km_per_s.

Referenced by radial_velocity(), and to_string().

## radial_velocity() [2/3]

CatalogEntry & supernovas::CatalogEntry::radial_velocity | ( | const ScalarVelocity & | v | ) |

Sets the radial velocity of this source relative to the Solar System Barycenter (SSB), defined at the same epoch as the catalog coordinates, and returning itself to enable builder pattern.

Parameters

  v | radial velocity with respect to the Solar System Barycenter (SSB)

Returns
  itself

Since
  1.6

See also
  v_lsr(), redshift()
  system(), distance(), parallax(), proper_motion(), catalog()

References CatalogEntry(), supernovas::ScalarVelocity::m_per_s(), and radial_velocity().

## radial_velocity() [3/3]

CatalogEntry & supernovas::CatalogEntry::radial_velocity | ( | double | v_ms | ) |

Sets the radial velocity of this source relative to the Solar System Barycenter (SSB), defined at the same epoch as the catalog coordinates, and returning itself to enable builder pattern.

Parameters

  v_ms | [m/s] radial velocity with respect to the Solar System Barycenter (SSB)

Returns
  itself

Since
  1.6

See also
  v_lsr(), redshift()
  system(), distance(), parallax(), proper_motion(), catalog()

References CatalogEntry(), supernovas::Validating::_valid, supernovas::Constant::c, supernovas::Unit::km_per_s, and novas_set_ssb_vel().

## redshift() [1/2]

double supernovas::CatalogEntry::redshift | ( |  | ) | const

Returns the barycentric redshift of the source, that is the redshift measure with respect to the Solar System Barycenter (SSB).

Returns
  the nominal redshift (rel. to the SSB) of the source, or 0.0 if the source motion was not explicitly defined.

Since
  1.6

See also
  system(), radial_velocity(), v_lsr()
  ra(), dec(), distance(), parallax()

References supernovas::Unit::km_per_s, and novas_v2z().

## redshift() [2/2]

CatalogEntry & supernovas::CatalogEntry::redshift | ( | double | z | ) |

Sets the redshift of this source relative to the Solar System Barycenter (SSB), defined at the same epoch as the catalog coordinates, and returning itself to enable builder pattern.

Parameters

  z | barycentric redshift measure.

Returns
  itself

Since
  1.6

See also
  radial_velocity(), v_lsr()
  system(), distance(), parallax(), proper_motion(), catalog()

References CatalogEntry(), supernovas::Validating::_valid, and novas_set_redshift().

## system()

const Equinox & supernovas::CatalogEntry::system | ( |  | ) | const

Returns the equatorial coordinate system in which this catalog entry is defined.

Returns
  the equatorial coordinate system of this catalog entry

Since
  1.6

See also
  ra(), dec(), distance(), parallax(), radial_velocity(), v_lsr(), redshift()

Referenced by CatalogEntry(), CatalogEntry(), supernovas::CatalogSource::CatalogSource(), and equatorial().

## to_string()

std::string supernovas::CatalogEntry::to_string | ( | int | decimals = 3 | ) | const

Returns a human-readable string representation of this catalog entry, showing only the most basic data.

Parameters

  decimals | [0:16] number of decimal places to print for coordinates.

Returns
  a string describing this catalog entry.

Since
  1.6

References distance(), equatorial(), name(), NOVAS_SEP_UNITS_AND_SPACES, radial_velocity(), supernovas::Coordinate::to_string(), supernovas::Equatorial::to_string(), and supernovas::ScalarVelocity::to_string().

## v_lsr() [1/3]

ScalarVelocity supernovas::CatalogEntry::v_lsr | ( |  | ) | const

Returns the scalar source velocity with respect to the Local Standard of Rest (LSR).

Returns
  the LSR velocity of the source (or the LSR velocity of the SSB if the source motion was not explicitly defined).

Since
  1.6

See also
  system(), radial_velocity(), redshift()
  ra(), dec(), distance(), parallax()

References supernovas::Validating::is_valid(), supernovas::Unit::km_per_s, and novas_ssb_to_lsr_vel().

Referenced by v_lsr().

## v_lsr() [2/3]

CatalogEntry & supernovas::CatalogEntry::v_lsr | ( | const ScalarVelocity & | v | ) |

Sets the motion of this source relative to the Local Standard of Rest (LSR), defined at the same epoch as the catalog coordinates, and returning itself to enable builder pattern.

Parameters

  v | LSR velocity

Returns
  itself

Since
  1.6

See also
  radial_velocity(), redshift()
  system(), distance(), parallax(), proper_motion(), catalog()

References CatalogEntry(), supernovas::ScalarVelocity::m_per_s(), and v_lsr().

## v_lsr() [3/3]

CatalogEntry & supernovas::CatalogEntry::v_lsr | ( | double | v_ms | ) |

Sets the motion of this source relative to the Local Standard of Rest (LSR), defined at the same epoch as the catalog coordinates, and returning itself to enable builder pattern.

Parameters

  v_ms | [m/s] LSR velocity

Returns
  itself

Since
  1.6

See also
  radial_velocity(), redshift()
  system(), distance(), parallax(), proper_motion(), catalog()

References CatalogEntry(), supernovas::Validating::_valid, supernovas::Constant::c, supernovas::Unit::km_per_s, and novas_set_lsr_vel().