SatCoord

class erwans3.Telescope_class.SatCoord(skycoord: Union[SkyCoord, BaseCoordinateFrame], att: Optional[AttitudeRepresentation] = None, obstime: Optional[Time] = None)

Bases: SkyCoord

High-level object providing a flexible interface to work with satellite coordinate representation with attitude representation. In particular, it helps with their manipulation, and transformation between systems. But it also provides various methods that applies to interferometers.

The SatCoord object can be initialized either using

a SkyCoord object and an AttitudeRepresentation
from_vec() classmethod by providing: position, velocity, attitude, frame and time

Parameters:

skycoord (SkyCoord or BaseCoordinateFrame) – SkyCoord or BaseCoordinateFrame instance defining the satellite’s coordinates.
att (AttitudeRepresentation or None, optional) – Attitude representation of the satellite, default is None.
obstime (Time or None, optional) – Observation time, default is None.

Raises:

TypeError – If attitude shape do not match the coordinate shape

Notes

This class extends SkyCoord to handle satellite coordinates including attitude representations and observation times.

Examples

>>> from astropy.coordinates import SkyCoord, BaseCoordinateFrame
>>> from astropy.time import Time
>>> from your_module import SatCoord

Define a SkyCoord instance >>> skycoord = SkyCoord(10, 20, 30, unit=’deg’)

Create a SatCoord instance >>> sat = SatCoord(skycoord)

Print the satellite coordinates >>> print(sat) <SatCoord (ICRS): (10., 20.)>

Check the attitude representation >>> print(sat._att) AttitudeRepresentation identity

Notes

This class assumes that the attitude shape matches the coordinate shape.

References

Astropy coordinates documentation
Astropy time documentation
Your module’s documentation for additional details.

Attributes Summary

`att`
`attrot`
`nsat`	Returns the number of satellites represented in this `SatCoord`
`pos`
`skycoord`	Returns a `SkyCoord` which is `SatCoord` without attitude
`times`	Returns the obstimes as a 1-dimensional array
`vel`

Methods Summary

`appox_size`()	Returns an approximation of the size of the swarm.
`barycenter`()	Returns the barycenter of the swarm at each time step as a \|SkyCoord\|
`baseline`([mode])	Returns the baselines of the swarm
`from_vec`(pos[, vel, att, frame, obstime])	Create a SatCoord instance from position, velocity and attitude vectors.
`get_time`(time)	Returns the coordinates of the satellites at a given time
`init_from_folder`(folder_path)	Initialize `SatCoord` using a list of files in a single folder.
`init_interpolation`()	Generate interpolation function for position, velocity and attitude
`longest_baseline`([axis])	Return the length of the longest baseline among the swarm.
`nbl`([mode])	Returns the number of baselines based with the specified mode.
`plot`([idx])	3D plot of the position in km
`transform_to`(frame)	Transform this coordinate to a new frame.
`uv_projection`(pointing[, u_dir, freq])	Compute the UV projection of the swarm's position relative to a pointing direction.

Attributes Documentation

att

attrot

nsat

Returns the number of satellites represented in this SatCoord

Default representation assumes that SatCoord.shape = (#sat, #time) But it can also be (#antenna, # station, #time) In the later, nsat() returns an array.

pos

skycoord: Returns a SkyCoord which is SatCoord without attitude

times: Returns the obstimes as a 1-dimensional array

vel

Methods Documentation

appox_size() → Quantity

Returns an approximation of the size of the swarm.

This method computes an approximation of the size of the swarm based on the singular value decomposition (SVD) of the Cartesian coordinates of the swarm. It extracts the singular values from the SVD to estimate the size.

return the approximate size of the swarm using the singular value decomposition method

Returns:: Approximation of the size of the swarm as a Quantity.
Return type:: Quantity

Examples

>>> # Assuming `swarm` is an initialized SatCoord instance
>>> approx_size = swarm.approx_size()
>>> print(approx_size)
1000.0 km  # Example result indicating the approximate size of the swarm in kilometers

barycenter() → SkyCoord: Returns the barycenter of the swarm at each time step as a |SkyCoord|

baseline(mode: str = 'tril')

Returns the baselines of the swarm

Compute the baseline coordinates of the swarm for every obstime according to a given mode.

Parameters:: mode (str, optional) – Choice of baseline calculation mode: - ‘all’: All possible baselines including redundant ones. - ‘tril’: Triangular matrix mode, excluding redundant baselines. - ‘solo_diag’: Only include autocorrelations (diagonal elements). - ‘tril_nodiag’: Triangular matrix mode without including autocorrelations.
Returns:: Baseline coordinates of the swarm for every obstime based on the specified mode.
Return type:: SatCoord

Notes

This method computes the baseline coordinates of the swarm for every obstime based on the specified mode. The mode determines which baselines are considered and how they are computed.

Examples

>>> # Assuming `swarm` is an initialized SatCoord instance
>>> baseline_coords = swarm.baseline(mode='tril')
>>> print(baseline_coords)
SatCoord(...)  # Example of baseline coordinates computed based on the specified mode

classmethod from_vec(pos: ~typing.Union[~astropy.units.quantity.Quantity, ~astropy.coordinates.representation.base.BaseRepresentation], vel: ~typing.Optional[~typing.Union[~astropy.units.quantity.Quantity, ~astropy.coordinates.representation.base.BaseRepresentationOrDifferential]] = None, att: ~typing.Optional[~typing.Union[~numpy.ndarray, ~erwans3.Telescope_class.AttitudeRepresentation]] = None, frame: ~astropy.coordinates.baseframe.BaseCoordinateFrame = <ICRS Frame>, obstime: ~typing.Optional[~astropy.time.core.Time] = None) → SatCoord

Create a SatCoord instance from position, velocity and attitude vectors.

Parameters:

pos (Quantity or BaseRepresentation) – Position vector or representation.
vel (Quantity or BaseRepresentationOrDifferential or None, optional) – Velocity vector or representation, default to 0m/s.
att (numpy.ndarray or AttitudeRepresentation or None, optional) – Attitude representation, default to identity.
frame (BaseCoordinateFrame, optional) – Reference coordinate frame, default is ICRS.
obstime (Time or None, optional) – Observation time, default is None.

Returns:

Instance of SatCoord created from the provided vectors and parameters.

Return type:

SatCoord

Notes

This class method creates a SatCoord instance using position and velocity vectors or representations, an optional attitude representation, a reference coordinate frame, and an observation time.

Examples

>>> from astropy.coordinates import CartesianRepresentation, CartesianDifferential
>>> from your_module import SatCoord

Define position and velocity vectors >>> pos_vec = CartesianRepresentation([1, 2, 3], unit=u.m) >>> vel_vec = CartesianDifferential([0, 0, 0], unit=u.m/u.s)

Create a SatCoord instance from vectors >>> sat = SatCoord.from_vec(pos_vec, vel=vel_vec)

See also

SatCoord.__init__(): Initialize SatCoord instance.

get_time(time: Time)

Returns the coordinates of the satellites at a given time

Compute the coordinates of the satellites at time based on an interpolation of the base coordinate. see method ‘init_interpolation’

Parameters:: time (~astropy.time.Time) – The time at which to compute the coordinates.
Returns:: A new SatCoord instance representing the coordinates of the satellites at the given time.
Return type:: SatCoord
Raises:: ValueError – If the specified time is outside of the interpolation range.

Notes

This method computes the coordinates of the satellites at the specified time by interpolating the base coordinate trajectory. It uses the init_interpolation method for initialization and performs interpolation based on the time difference from J2000.

Examples

>>> from astropy.time import Time
>>> # Assuming `sat` is an initialized SatCoord instance
>>> t = Time('2024-03-21T12:00:00')
>>> new_sat = sat.get_time(t)
>>> print(new_sat)
SatCoord(...)  # Example of the new SatCoord instance at the specified time

See also

init_interpolation(): Initialize interpolation for coordinates.

classmethod init_from_folder(folder_path: Union[str, Path])

Initialize SatCoord using a list of files in a single folder.

The files are assumed to follow the CIC protocol. More information can be found at: https://gitlab.isae-supaero.fr/nanostar/adcs-module/-/blob/master/Doc/CIC-Exchange-Protocol-V2.0.pdf

Parameters:: folder_path (str or Path) – Path to a folder containing the trajectory files in .txt format.
Returns:: Initialized SatCoord instance.
Return type:: SatCoord

Notes

This class method reads trajectory files from the specified folder path and initializes a SatCoord instance using the data from these files. It uses the metadata from the trajectory files to determine the reference frame and other parameters necessary for initialization.

Examples

>>> from erwans3.Telescope import SatCoord

Initialize SatCoord from a folder path >>> folder_path = ‘/path/to/trajectory_folder/’ >>> sat_coord = SatCoord.init_from_folder(folder_path)

See also

erwans3.Telescope_class.SatCoord.__init__(): Initialize SatCoord instance.

init_interpolation()

Generate interpolation function for position, velocity and attitude

as hidden attributes. used for the method ‘get_time’ Multiple obstime must be provided in order to run it.

longest_baseline(axis: Optional[Union[int, tuple]] = None) → Quantity

Return the length of the longest baseline among the swarm.

Parameters:: axis (int or tuple or None, optional) – Axis or axes along which to operate. By default, computes the maximum over all axes. If specified as an integer or tuple of integers, computes the maximum along the specified axes.
Returns:: Length of the longest baseline among the swarm as a Quantity.
Return type:: astropy.units.Quantity

Notes

This method computes the length of the longest baseline among the swarm’s baseline coordinates, which are obtained using the ‘tril’ mode of the baseline computation.

Examples

>>> # Assuming `swarm` is an initialized SatCoord instance
>>> longest_length = swarm.longest_baseline()
>>> print(longest_length)
1000.0 km  # Example result indicating the longest baseline length in kilometers

See also

baseline(): Compute baseline coordinates of the swarm.

nbl(mode: str = 'tril') → int

Returns the number of baselines based with the specified mode.

Parameters:: mode (str, optional) – Choice of baseline calculation mode: - ‘all’: All possible baselines including redundant ones. - ‘tril’: Triangular matrix mode, excluding redundant baselines. - ‘solo_diag’: Only include autocorrelations (diagonal elements). - ‘tril_nodiag’: Triangular matrix mode without including autocorrelations.
Returns:: Number of baselines based on the specified mode.
Return type:: int

Notes

The method calculates the number of baselines based on the specified mode. The ‘tril’ mode excludes redundant baselines, while ‘all’ mode includes all baselines, including redundant ones.

Examples

>>> # Create a SatCoord instance
>>> sat = SatCoord.from_vec(CartesianRepresentation(np.ones((3,5))))
>>> # Get the number of baselines in tril mode
>>> num_baselines = sat.nbl(mode='tril')
>>> print(num_baselines)
10  # Example result based on the number of satellites

See also

baseline(): a method that returns the baselines of the swarm with the same mode.

plot(idx: Optional[Union[int, slice, tuple]] = None): 3D plot of the position in km

transform_to(frame: BaseCoordinateFrame)

Transform this coordinate to a new frame.

The precise frame transformed to depends on merge_attributes. If False, the destination frame is used exactly as passed in. But this is often not quite what one wants. E.g., suppose one wants to transform an ICRS coordinate that has an obstime attribute to FK4; in this case, one likely would want to use this information. Thus, the default for merge_attributes is True, in which the precedence is as follows: (1) explicitly set (i.e., non-default) values in the destination frame; (2) explicitly set values in the source; (3) default value in the destination frame.

Note that in either case, any explicitly set attributes on the source |SkyCoord| that are not part of the destination frame’s definition are kept (stored on the resulting |SkyCoord|), and thus one can round-trip (e.g., from FK4 to ICRS to FK4 without losing obstime).

Parameters:

frame (str, ~astropy.coordinates.BaseCoordinateFrame class or instance, or |SkyCoord| instance) – The frame to transform this coordinate into. If a |SkyCoord|, the underlying frame is extracted, and all other information ignored.
merge_attributes (bool, optional) – Whether the default attributes in the destination frame are allowed to be overridden by explicitly set attributes in the source (see note above; default: True).

Returns:

coord – A new object with this coordinate represented in the frame frame.

Return type:

|SkyCoord|

Raises:

ValueError – If there is no possible transformation route.

uv_projection(pointing: Union[ndarray, BaseRepresentation, BaseCoordinateFrame], u_dir: Optional[Union[ndarray, BaseRepresentation, BaseCoordinateFrame]] = None, freq: Optional[Quantity] = None) → Union[ndarray, Quantity]

Compute the UV projection of the swarm’s position relative to a pointing direction.

This method computes the UV projection of the swarm’s position relative to a specified pointing direction. The UV projection is used in radio interferometry to represent baseline coordinates in the UV-plane.

Returns the satcoord projected in a plane normal to ‘pointing’ (uv projection with pointing=w) This function should be run on the baselines represented as satcoord to perform interferometry

Parameters:

pointing (ndarray or BaseRepresentation or BaseCoordinateFrame) – Pointing direction vector or coordinate frame.
u_dir (ndarray or BaseRepresentation or BaseCoordinateFrame or None, optional) – U-direction vector or coordinate frame. If not provided, it is calculated based on the pointing direction.
freq (Quantity`[`Hz] or None, optional) – Frequency for converting positions to wavelength units. Default is None.

Returns:

UV projection of the swarm’s position relative to the pointing direction. If a frequency is provided, the result is returned in wavelength units.

Return type:

ndarray or Quantity

Raises:

TypeError – If the input types for pointing or u_dir are not supported, or if the shapes of vectors are incorrect.

Notes

If u_dir is not provided, it is calculated based on the pointing direction and the Earth’s zenith.
The UV projection represents the baseline coordinates in the UV-plane for radio interferometry.

Examples

>>> # Assuming `swarm` is an initialized SatCoord instance
>>> # Define pointing direction and frequency
>>> pointing_dir = np.array([1, 0, 0])  # Example pointing direction along x-axis
>>> frequency = 100 * u.MHz
>>> # Compute UV projection
>>> uv_proj = swarm.uv_projection(pointing=pointing_dir, freq=frequency)
>>> print(uv_proj)
[1.2345 0.5678]  # Example UV projection coordinates in wavelength units