test_eclipse

test_eclipse.test_annularEclipseIlluminationFactor(distanceBehindEarth, boundaryFraction)

Test Description and Success Criteria

A spacecraft is placed beyond the tip of the umbra, which extends about 1.39e9 m behind the Earth, so that the disk of the Earth lies entirely inside the solar disk. The spacecraft is either on the Earth shadow axis or displaced laterally until the Earth disk nearly touches the edge of the solar disk, which checks the annular branch selection just inside the annular/partial boundary. The Sun, Earth and spacecraft states are written directly to messages, which makes the truth value independent of Spice. Before running the simulation, the test asserts that the setup is annular, i.e. \(a > b\) and \(c < a - b\), where \(c\) is the apparent angular separation of the Sun and Earth centers.

The illumination factor must equal the visible fraction of the solar disk, \(1 - (b/a)^2\), where \(a\) and \(b\) are the apparent radii of the Sun and the Earth seen from the spacecraft, and not the occulted fraction \((b/a)^2\).

Test Parameters:

• distanceBehindEarth: [m] distance of the spacecraft from the Earth along the shadow axis

• boundaryFraction: [-] target value of \(c / (a - b)\), where 0 places the spacecraft on the shadow axis and values close to 1 place it just inside the annular/partial boundary

Description of Variables Being Tested

The illuminationFactor of the eclipse output message is compared to the analytic truth value.

test_eclipse.test_eclipse_uses_spacecraft_state_extrapolated_to_step_midpoint()

Test Description and Success Criteria

The spacecraft state message read by the module was written at the end of the previous step, so the illumination factor lags the interval it is applied to. The module therefore advances the spacecraft position with its velocity by half of the message age.

A spacecraft is placed outside the Earth shadow, moving towards it fast enough that the position advanced by half a step is inside the shadow. The state is given to one module with its velocity, written at the start of the simulation and rewritten one step later, and to a second module as the already advanced position written at the current time. The two illumination factors must match, and both must differ from a static spacecraft that does not move.

test_eclipse.test_shadow_vs_illumination_alias_and_deprecation_behavior()

Check aliasing and deprecation behavior for EclipseMsgPayload.

If this test starts failing with a BSKUrgentDeprecationWarning (or the deprecation utility starts treating shadowFactor as an error), that is a signal that we have passed the deprecation deadline and should:

• remove support for EclipseMsgPayload.shadowFactor, and

• remove this test (or update it to only check illuminationFactor).

test_eclipse.test_unitEclipse(show_plots, eclipseCondition, planet)

Test Description and Success Criteria

The unit test validates the internal aspects of the Basilisk eclipse module by comparing simulated output with expected output. It validates the computation of a illumination factor for total eclipse, partial eclipse,annular eclipse, and no eclipse scenarios. The test is designed to analyze one type at a time for both Earth and Mars and is then repeated for all three.

Earth is set as the zero base for all eclipse types to test it as the occulting body. For full, partial, and no eclipse cases, orbital elements describing the spacecraft states are then converted to Cartesian vectors. These orbital elements vary for each eclipse type since the Sun and planet states are fixed. The conversion is made using the orbitalMotion elem2rv function, where the inputs are six orbital elements (a, e, i, Omega, omega, f) and the outputs are Cartesian position and velocity vectors. For the annular eclipse case, the conversion is avoided and a Cartesian position vector is initially provided instead. The vectors are then passed into spacecraft and, subsequently, the eclipse module through the Basilisk messaging system.

Testing the no eclipse case with Mars as the occulting body is the same as the Earth no eclipse test, except Mars is set as the zero base. The Mars full, partial, and annular eclipse cases, however, are like the Earth annular case where Cartesian vectors are, instead, the initial inputs. Since the test is performed as a single step process, the velocity is not necessarily needed as an input, so only a position vector is provided for these cases.

The illumination factor obtained through the module is compared to the expected result, which is either trivial or calculated, depending on the eclipse type. Full eclipse and no eclipse illumination factors are compared without the need for computation, since they are just 0.0 and 1.0, respectively. The partial and annular eclipse illumination factors, however, vary between 0.0 and 1.0, based on the cone dimensions, and are calculated using MATLAB and Spice data. In the annular cases the disk of the planet lies inside the solar disk, so the truth value is the visible fraction \(1 - (b/a)^2\) of the solar disk, where \(a\) and \(b\) are the apparent radii of the Sun and the planet.

Test Parameters:

• eclipseCondition: [string] defines if the eclipse is partial, full, none or annular

• planet: [string] defines which planet to use. Options include “earth” and “mars”

Description of Variables Being Tested

In each test scenario the illumination eclipse variable

illuminationFactor

is pulled from the log data and compared to expected truth values.

test_eclipse.test_unitEclipseCustom(show_plots)

Test Description and Success Criteria

The unit test validates the internal aspects of the Basilisk eclipse module by comparing simulated output with expected output. It validates the computation of a illumination factor for total eclipse using a custom gravity body.

This unit test sets up a custom gravity body, the asteroid Bennu, using the planetEphemeris module (i.e. Spice is not used for this test.) An empty spice planet message is created for the sun. The spacecraft is set 500 m on the side of the asteroid opposite of the sun.

The illumination factor obtained through the module is compared to the expected result, which is trivial to compute.

Description of Variables Being Tested

In this test scenario the illumination eclipse variable

illuminationFactor

is pulled from the log data and compared to the expected truth value.