Guide ===== .. _installation: Installation ------------ The latest version is available on `PyPi`_. Ensure that pip is installed and run the following command: .. code-block:: console pip install spacevlbi Installing with pip will install/update all of the required libraries automatically (`numpy`_, `poliastro`_, `matplotlib`_, `astropy`_). .. _numpy: http://www.numpy.org/ .. _poliastro: https://www.poliastro.space/ .. _matplotlib: http://www.matplotlib.org/ .. _astropy: http://www.astropy.org/ .. _PyPi: https://pypi.org/project/spacevlbi/ .. _introduction: Introduction ------------ **spacevlbi** relies on creation of a number of key class objects and execution of the ``TimeLoop()`` function to conduct a simulation of a space VLBI mission. The ``SpaceTelescope`` class enables an Earth-orbiting space telescope to be modelled, including a range of its main components that can affect when observations can take place (see the :ref:`spacetelescope` and :ref:`constraints` sections below). The ``GroundTelescope`` class enables a ground-based radio antenna to be modelled so that ground-space VLBI baselines can be calculated (see the :ref:`groundtelescope` section below for more information). The ``GroundStation`` class enables a ground-based station for space telescope Telemetry, Tracking and Command (TT&C) to be modelled. This is useful for calculating the impact of a number of functional constraints (see the :ref:`groundstation` and :ref:`constraints` sections below). To model a purely space-based VLBI mission, two or more ``SpaceTelescope`` objects must be created. To model a ground-space VLBI mission, two or more ``SpaceTelescope`` and ``GroundTelescope`` objects must be created. ``GroundStation`` objects are not mandatory in order to run a simulation but are required for inclusion of some of the functional constraints. Once the desired VLBI array has been defined by creating objects of the classes described above, the ``TimeLoop()`` function is executed to run the simulation over a defined time period and with a specific step size. At each time step, the ``TimeLoop()`` function: 1. Propagates space telescope(s) orbit 2. Propagates space telescope(s) attitude 3. Calculates Moon and Sun positions 4. Calculates range and elevation from ground station(s) to space telescopes(s) (if ground stations are modelled) 5. Calculates whether any functional constraints are prohibiting observations 6. Calculates the baselines and subsequent (u,v) coverage generated by the array of a specific source (or for a range of sources across the celestial sphere if the ``allsky`` parameter is set to 1 in the execution of ``TimeLoop()``) Once the ``TimeLoop()`` function has finished executing, the results of the simulation are returned within the ``SpaceTelescope``, ``GroundTelescope`` and ``GroundStation`` objects. A number of figure types are then available to the user to plot key results: * ``OrbitPlot()`` - Plot of the space telescope orbits about the Earth * ``UvPlot()`` - Plot of the (u,v) coverage achieved by the array, including the impact of any functional constraints modelled * ``AttitudeSphere()`` - Plot of a specified space telescope's attitude sphere in the body-fixed frame including Sun, Earth and Moon positions throughout the simulation and the positions of any spacecraft components that have been modelled * ``SolarPanelIncidence()`` - Plot of the angle between the Sun and the spacecraft's panel normal vectors throughout the simulation * ``GroundStationElevation()`` - Plot of the elevation angle from each ground station to a specified space telescope throughout the simulation Provided in the Examples folder is the script ``ExampleSetup.py``. This script shows how the package can be used to model a VLBI array with a single space element. This example is based upon the preliminary concept for the `BHEX`_ mission. The script ``ExampleSpaceTelescope.py`` shows how an object of the ``SpaceTelescope`` class can be defined. .. _BHEX: https://www.blackholeexplorer.org/ .. _spacetelescope: Space Telescope --------------- A ``SpaceTelescope`` is created by defining a range of mass and configuration properties. The spacecraft orbit is defined using classical Keplerian elements and an initial true anomaly at the start of the simulation. The attitude state of the spacecraft throughout the simulation must also be provided in terms of a roll angle (see :ref:`attitudeprop` section below). As well as these properties, the user can attach a number of component objects to a space telescope to model the key equipment onboard that can impact when observations can be performed by the system. .. _radiopayload: Radio Payload ~~~~~~~~~~~~~ Properties of the space telescope related to the radio observations are defined as part of a ``RadioPayload`` object. The radio payload includes definition of the antenna diameter, boresight and properties of the payload receiver electronics required to calculate the System Equivalent Flux Density (SEFD) of the telescope. Sun, Earth and Moon exclusion angles can also be included to model the functional constraint on observations imposed by thermal distortion of the science antenna due to heat input from these celestial bodies. The exclusion angles work as follows: at any time step during the simulation, if the angle between the antenna boresight (its pointing direction) and the Sun / Earth / Moon is less than the defined exclusion angle, an observation cannot take place. Multiple radio payloads can be modelled and attached to the spacecraft. However, simulation of observations at only one frequency are currently permitted per simulation run. .. _startracker: Star Tracker ~~~~~~~~~~~~ Star trackers are implemented onboard spacecraft that require high attitude control accuracy for their mission. Astronomy missions such as space-based VLBI are an example of such missions requiring very high attitude knowledge accuracy which can only be provided by star trackers. A star tracker is a sensitive camera that captures images of the celestial sphere. It identifies the stars in the image and compares them to an internal star catalogue and finally estimates the attitude state of the spacecraft by analysing the rotation of the star field in its Field-Of-View (FOV). Star trackers typically have a limitation on the angle between their boresight and the Sun / Earth and sometimes Moon limbs. Sun, Earth and Moon exclusion angles can therefore be modelled to include this effect. When an exclusion angle is violated, it is assumed that the specific star tracker will not be providing useful attitude information and the star tracker is considered to be in a *blinded* state. The user can attach any number of star trackers to a space telescope by creating a ``StarTracker`` object. As part of the ``SpaceTelescope`` object, the user must also define the number of star trackers required to provide sufficient attitude control accuracy in order to perform an observation, using the ``reqStarTrackers`` parameter. The star tracker functional constraint works as follows: if at the current timestep the number of unblinded star trackers is less than the ``reqStarTrackers`` parameter, an observation cannot take place. .. _radiator: Radiator ~~~~~~~~ Radiators are required onboard spacecraft that must provide a low temperature thermal environment to specific pieces of equipment. They are often used in conjunction with cyrogenic cooling systems for astronomy missions to provide a low noise environment for the detection of weak astronomical signals. The user can define any number of ``Radiator`` objects and attach them to a space telescope. Radiators must typically be pointed towards deep space to achieve the low temperatures required by missions such as space VLBI. As such, the user can define Sun, Earth and Moon exclusion angles for each radiator to model the implementation of a baffle or shade on the radiator to reduce the angle at which energy from the Sun / Earth / Moon falls upon its surface. The radiator functional constraint works as follows: if at the current timestep the Sun / Earth / Moon exclusion angles for any of the modelled radiators are violated, an observation cannot take place. In reality, it may be permissible for some radiators to have the Sun / Earth / Moon within their FOV for a small period of time. However, such time dependence on the functional constraint is not currently modelled in the tool. The ``Radiator`` object can also be used to model more general thermal constraints on the spacecraft. For example, if there is a particular component or direction which cannot be pointed towards the Sun / Earth / Moon. .. _solarpanel: Solar Panel ~~~~~~~~~~~ Solar panels are utilised for almost all near-Earth operating spacecraft as a primary source of power generation. The power generated by a solar panel is directly proportional to the cosine of the angle between the panel normal vector and the incident solar radiation. The user can model any number of solar panels onboard the spacecraft by defining a ``SolarPanel`` object. There is currently no functional constraint attached to the ``SolarPanel`` object within the tool. They can simply be used to conduct an initial investigation into the likely power generation capabilities of the system during observations by understanding how the solar incidence angle on the panel varies. In the future, the tool could be upgraded to enable more complete calculation of power generation and the implementation of a functional constraint defining the minimum power required to perform an observation. Batteries are also not currently modelled within the tool. .. _commssystem: Communication System ~~~~~~~~~~~~~~~~~~~~ The user can define what is known as a ``CommsSystem`` object within the tool that can be used to model communications antennas or optical terminals onboard the spacecraft. Multiple ``CommsSystem`` objects can be defined, enabling the differentiation between TT&C antennas and antennas / optical terminals for payload data downlink, if required. A ``CommsSystem`` object is defined by definition of the normal vector of the unit in the spacecraft body-fixed frame. In the case of an antenna, this would be the normal vector of the antenna surface. In the case of an optical terminal with a gimballing capability, this would be the direction of the terminal when at 0 degrees gimbal. The user can also define a 'FOV' of the system, within which, if a ground station is insight, a communications link with the spacecraft can be maintained. For a radio antenna, the 'FOV' parameter can be considered as the half beamwidth within which there is sufficient signal power to perform communications with the ground. For an optical terminal, the 'FOV' parameter can be considered the limit of the unit's gimbal capability, measured from the normal vector. As part of the ``CommsSystem`` object, the user can also define whether a link with the ground is required during observations. This would be necessary for systems performing real-time downlink of astronomical data and / or those requiring a link with the ground for provision of a frequency standard. .. _groundtelescope: Ground Telescope ---------------- The user can define any number of ``GroundTelescope`` objects as part of the VLBI array by specifying the location of the antenna in the Earth-Centered Earth-Fixed (ECEF) frame and a minimum elevation above which observations of a source can take place. Additional properties of the receiver electronics required to calculate the SEFD of the telescope can also be defined. .. _groundstation: Ground Station -------------- To assess the access times between the ground and the spacecraft from a TT&C perspective, the user can define any number of ``GroundStation`` objects. During the simulation, the range and elevation of all space telescopes is calculated for each ground station. To include the functional constraint related to either the real-time downlink of data or the provision of a frequency standard to the space telescope, the user can set the ``groundReqObs`` parameter on the space telescope. This will ensure that observations can only be conducted when a ground station is insight of the communication systems 'FOV'. The user can also specify a minimum elevation at the ground station above which a link with the space telescope can be maintained. Note: If the simulation timestep is too low the elevation and range calculated for each space telescope will be truncated and the maximum values shown may not be true. .. _orbitprop: Orbit Propagation ----------------- During the simulation, the orbit of each ``SpaceTelescope`` object is propagated using the Python package `poliastro`_. Poliastro's Orbit functionality can be used to perform a two-body propagation of a spacecraft's orbit and also include additional perturbing forces. The following perturbing forces are currently included in the orbit propagation: * J2 and J3 Earth gravitational field harmonics * Third body perturbation from the Moon and Sun, modelled as point mass contributions * Atmospheric drag utilising the exponential density model built in to `poliastro`_ * Solar radiation pressure utilising a solar flux that can be varied by the user Additional perturbing forces could be included by editing the ``Force_Wrapper()`` function in which are calculated the accelerations imparted by each perturbation. .. _poliastro: https://www.poliastro.space/ .. _attitudeprop: Attitude Propagation -------------------- In order to model the functional constraints impacting space telescope operation, the attitude of the spacecraft is propagated within the tool. The propagation of the attitude state is a calculation of the attitude matrix required to rotate the inertial frame into the body-fixed frame of the spacecraft. Errors in the contrl accuracy are not included as their effect on the impact of functional constraints is negligible. The ``pointingVector`` parameter defines the body-fixed axis of the spacecraft to point towards the target source throughout the simulation. The ``constraintVector`` parameter defines the body-fixed axis used to constrain the 3-axis attitude of the spacecraft and is pointed in a direction perpendicular to the target source. It is essential that the pointing and constraint vectors are also perpendicular to each other. The user can also specify the ``rollAngle`` parameter which defines the spacecraft's rotation about the pointing direction. The ``rollAngle`` parameter includes a combination of time - roll angle pairs defining the roll angle at different simulation times. This enables the attitude state of the space telescope to be varied throughout the simulation. The roll angle parameter is measured from the plane in which lies the celestial north pole direction and the target source direction. If viewing along the antenna boresight, the roll angle is measured in a positive direction. .. image:: RollAngle.png :height: 400px Future iterations of the tool may include other attitude control modes to model a wider range of spacecraft operations (e.g. Nadir pointing, Sun pointing, etc.). .. _constraints: Functional Constraints ---------------------- One of the main purposes of the ``spacevlbi`` package is to assess the impact of elements of the spacecraft and wider interferometer system design on when observations can be performed and subsequently, the science return of the mission. VLBI is unique amongst science applications of space in the complexity of its operation. It requires a highly performant spacecraft but also the mission architecture consists of multiple, complex relationships with systems on the ground (E.g. ground telescopes, ground stations). ``spacevlbi`` can be used to assess the impact of what are referred to in this tool as *functional constraints* and optimise the design of the spacecraft and mission architecture to mitigate their effect on observations. Each object within the tool has some functional constraint associated with it and the specifics of the constraints are described throughout this guide. However, as a summary, the following constraints can be modelled with ``spacevlbi``: * Visibility of target source to space and ground telescopes (i.e. source is not blocked by the Earth) * Minimum elevation limits of ground telescopes * Science antenna Sun, Earth and Moon limb exclusion angles * Spacecraft star tracker Sun, Earth and Moon exclusion angles to assess blinding which impacts attitude control accuracy * Spacecraft radiator Sun, Earth and Moon exclusion angles impacting thermal control * Spacecraft communications for real-time downlink and provision of frequency standard Although the solar incidence angle on the spacecraft's panels are not actively linked to a functional constraint within the tool, they can be used to conduct a preliminary assessment of the power generation capabilities of the spacecraft during observations. .. _optimisation: Optimisation ------------ The ``Optimisation()`` function can be used to find the optimal position of a specific spacecraft component to minimise the impact of its functional constraint on observations. The functional constraint of the component must be able to be defined in terms of a specific Sun / Earth / Moon relationship. The function uses the outputs from a full simulation run and iterates through a range of positions (defined as unit vectors in the body-fixed frame which the component in question will be pointed along) covering the full attitude sphere of the spacecraft. For each position, the function calculates the angle to the Sun / Earth / Moon limb and checks these against their definition in the function parameters to determine the position's fitness. The function returns the full list of evaluated positions along with their fitness (defined as the percentage of the simulation for which the functional constraint impacts observations). Some examples of how the ``Optimisation()`` function can be used include: * Star tracker position - User specifies minimum Sun / Earth / Moon exclusion angles for star tracker to provide useful attitude estimation and sets the ``direction`` parameter to "greaterthan" * Radiator position - User specifies minimum Sun / Earth / Moon exclusion angles for radiator to provide required thermal emission and sets the ``direction`` parameter to "greaterthan" * Communications system position - User specifies minimum Earth angle for comms system to achieve a link with the ground and sets the ``direction`` parameter to "lessthan".