[1323] downlinkHandling: expand unit tests and add debug toggle

Author: dhutererprats

src/simulation/communication/downlinkHandling/_UnitTest/test_downlinkHandling.py

@@ -21,6 +21,7 @@
 - Formula parity against the Python-equivalent BER/PER/ARQ model.
 - Zero-throughput behavior when link quality inputs are invalid.
 - Retry-cap effects on storage drawdown and packet drop probability.
+- Removal-policy behavior (attempted removal vs delivered-only removal).
 - Storage-limited operation and remaining-data estimate behavior.
 - Automatic receiver-path selection from linkBudget antenna states/CNR values.
 
@@ -45,6 +46,10 @@
 
 DownlinkHandlingMsgPayload = importlib.import_module("Basilisk.architecture.messaging.DownlinkHandlingMsgPayload")
 LinkBudgetMsgPayload = importlib.import_module("Basilisk.architecture.messaging.LinkBudgetMsgPayload")
+DataStorageStatusMsgPayload = importlib.import_module("Basilisk.architecture.messaging.DataStorageStatusMsgPayload")
+
+REMOVE_ATTEMPTED = 0
+REMOVE_DELIVERED_ONLY = 1
 
 # Debug is false by default; can be enabled by environment variable or --debug when running this file directly.
 DEBUG_DOWNLINK_TEST = False
@@ -72,7 +77,7 @@ def q_function(x):
     return 0.5 * math.erfc(x / math.sqrt(2.0))
 
 
-def python_equivalent_from_link(cnr_linear, bandwidth_hz, bit_rate_bps, packet_bits, max_retx):
+def python_equivalent_from_link(cnr_linear, bandwidth_hz, bit_rate_bps, packet_bits, max_retx, removal_policy=REMOVE_ATTEMPTED):
     cnr_db = 10.0 * math.log10(cnr_linear)
     c_n0_dbhz = cnr_db + 10.0 * math.log10(bandwidth_hz)
     eb_n0_db = c_n0_dbhz - 10.0 * math.log10(bit_rate_bps)
@@ -90,9 +95,13 @@ def python_equivalent_from_link(cnr_linear, bandwidth_hz, bit_rate_bps, packet_b
     else:
         expected_attempts = packet_success / one_try_success
 
-    storage_removal_rate = bit_rate_bps / expected_attempts
-    delivered_rate = storage_removal_rate * packet_success
-    dropped_rate = storage_removal_rate - delivered_rate
+    modeled_storage_removal_rate = bit_rate_bps / expected_attempts
+    delivered_rate = modeled_storage_removal_rate * packet_success
+    dropped_rate = modeled_storage_removal_rate - delivered_rate
+    if removal_policy == REMOVE_DELIVERED_ONLY:
+        storage_removal_rate = delivered_rate
+    else:
+        storage_removal_rate = modeled_storage_removal_rate
 
     return {
         "c_n0_dbhz": c_n0_dbhz,
@@ -108,6 +117,21 @@ def python_equivalent_from_link(cnr_linear, bandwidth_hz, bit_rate_bps, packet_b
     }
 
 
+def make_storage_status_msg(storage_level_bits, partition_entries):
+    payload = DataStorageStatusMsgPayload.DataStorageStatusMsgPayload()
+    payload.storageLevel = storage_level_bits          # [bit]
+
+    names = DataStorageStatusMsgPayload.StringVector()
+    values = DataStorageStatusMsgPayload.DoubleVector()
+    for name, bits in partition_entries:
+        names.push_back(name)
+        values.push_back(bits)                         # [bit]
+
+    payload.storedDataName = names
+    payload.storedData = values
+    return DataStorageStatusMsgPayload.DataStorageStatusMsg().write(payload)
+
+
 def run_downlink_case(
     cnr1=0.0,
     cnr2=0.5,
@@ -118,6 +142,7 @@ def run_downlink_case(
     packet_bits=256.0,
     max_retx=10,
     receiver_index=2,
+    removal_policy=REMOVE_ATTEMPTED,
     initial_bits=1.0e9,
     task_dt_s=1.0,
     stop_time_s=3.0
@@ -127,6 +152,7 @@ def run_downlink_case(
         f"cnr1={cnr1}, cnr2={cnr2}, bandwidth_hz={bandwidth_hz}, "
         f"bit_rate_bps={bit_rate_bps}, packet_bits={packet_bits}, "
         f"max_retx={max_retx}, receiver_index={receiver_index}, "
+        f"removal_policy={removal_policy}, "
         f"initial_bits={initial_bits}, task_dt_s={task_dt_s}, stop_time_s={stop_time_s}"
     )
     unit_task_name = "unitTask"
@@ -138,11 +164,12 @@ def run_downlink_case(
 
     test_module = downlinkHandling.DownlinkHandling()
     test_module.ModelTag = "downlink"
-    test_module.bitRateRequest = bit_rate_bps
-    test_module.packetSizeBits = packet_bits
-    test_module.maxRetransmissions = max_retx
-    test_module.receiverAntenna = receiver_index
-    test_module.requireFullPacket = True
+    assert test_module.setBitRateRequest(bit_rate_bps)
+    assert test_module.setPacketSizeBits(packet_bits)
+    assert test_module.setMaxRetransmissions(max_retx)
+    assert test_module.setReceiverAntenna(receiver_index)
+    assert test_module.setRemovalPolicy(removal_policy)
+    test_module.setRequireFullPacket(True)
     unit_test_sim.AddModelToTask(unit_task_name, test_module)
 
     data_storage = simpleStorageUnit.SimpleStorageUnit()
@@ -183,6 +210,7 @@ def run_downlink_case(
         debug_print(
             "case results: "
             f"linkActive={downlink_log.linkActive[-1]}, "
+            f"removalPolicy={downlink_log.removalPolicy[-1]}, "
             f"receiverIndex={downlink_log.receiverIndex[-1]}, "
             f"ber={downlink_log.ber[-1]:.16e}, per={downlink_log.per[-1]:.16e}, "
             f"storageRemovalRate={downlink_log.storageRemovalRate[-1]:.16e}, "
@@ -196,6 +224,7 @@ def run_downlink_case(
 
 
 def test_downlink_matches_python_equivalent():
+    """Verify C++ module outputs match the Python-equivalent BER/PER/ARQ model."""
     debug_print("test_downlink_matches_python_equivalent")
     cnr = 0.5
     bandwidth = 1.0e6
@@ -222,6 +251,7 @@ def test_downlink_matches_python_equivalent():
     debug_compare("nodeBaudRate", node_log.baudRate[-1], -expected["storage_removal_rate"])
 
     assert downlink_log.linkActive[-1] == 1
+    assert downlink_log.removalPolicy[-1] == REMOVE_ATTEMPTED
     assert downlink_log.ber[-1] == pytest.approx(expected["ber"], rel=1e-12, abs=1e-15)
     assert downlink_log.per[-1] == pytest.approx(expected["per"], rel=1e-12, abs=1e-15)
     assert downlink_log.expectedAttemptsPerPacket[-1] == pytest.approx(expected["expected_attempts"], rel=1e-12, abs=1e-15)
@@ -232,6 +262,7 @@ def test_downlink_matches_python_equivalent():
 
 
 def test_downlink_invalid_link_outputs_zero_flow():
+    """Verify invalid link inputs produce zero link-active flag and zero throughput."""
     debug_print("test_downlink_invalid_link_outputs_zero_flow")
     _, node_log, _, downlink_log = run_downlink_case(
         cnr2=0.0,
@@ -250,6 +281,7 @@ def test_downlink_invalid_link_outputs_zero_flow():
 
 
 def test_downlink_retry_limit_changes_storage_draw_not_goodput():
+    """Verify higher retry caps reduce storage draw while preserving expected delivered-rate level."""
     debug_print("test_downlink_retry_limit_changes_storage_draw_not_goodput")
     common = dict(
         cnr2=0.5,
@@ -276,7 +308,51 @@ def test_downlink_retry_limit_changes_storage_draw_not_goodput():
     assert downlink_log_m1.deliveredDataRate[-1] == pytest.approx(downlink_log_m8.deliveredDataRate[-1], rel=1e-12, abs=1e-9)
 
 
+def test_downlink_remove_delivered_only_retains_undelivered_bits():
+    """Verify delivered-only removal mode keeps dropped/undelivered bits onboard."""
+    debug_print("test_downlink_remove_delivered_only_retains_undelivered_bits")
+    common = dict(
+        cnr2=0.5,
+        bandwidth_hz=1.0e6,
+        bit_rate_bps=1.0e5,
+        packet_bits=256.0,
+        max_retx=4,
+        initial_bits=1.0e9,
+        stop_time_s=3.0
+    )
+
+    _, node_attempted, storage_attempted, downlink_attempted = run_downlink_case(
+        removal_policy=REMOVE_ATTEMPTED, **common
+    )
+    _, node_delivered, storage_delivered, downlink_delivered = run_downlink_case(
+        removal_policy=REMOVE_DELIVERED_ONLY, **common
+    )
+
+    assert downlink_attempted.removalPolicy[-1] == REMOVE_ATTEMPTED
+    assert downlink_delivered.removalPolicy[-1] == REMOVE_DELIVERED_ONLY
+
+    assert downlink_attempted.attemptedDataRate[-1] == pytest.approx(
+        downlink_delivered.attemptedDataRate[-1], rel=1e-12, abs=1e-9
+    )
+    assert downlink_attempted.deliveredDataRate[-1] == pytest.approx(
+        downlink_delivered.deliveredDataRate[-1], rel=1e-12, abs=1e-9
+    )
+    assert downlink_attempted.droppedDataRate[-1] == pytest.approx(
+        downlink_delivered.droppedDataRate[-1], rel=1e-12, abs=1e-9
+    )
+
+    assert downlink_attempted.storageRemovalRate[-1] > downlink_delivered.storageRemovalRate[-1]
+    assert downlink_delivered.storageRemovalRate[-1] == pytest.approx(
+        downlink_delivered.deliveredDataRate[-1], rel=1e-12, abs=1e-9
+    )
+
+    assert node_attempted.baudRate[-1] == pytest.approx(-downlink_attempted.storageRemovalRate[-1], rel=1e-12, abs=1e-9)
+    assert node_delivered.baudRate[-1] == pytest.approx(-downlink_delivered.storageRemovalRate[-1], rel=1e-12, abs=1e-9)
+    assert storage_delivered.storageLevel[-1] > storage_attempted.storageLevel[-1]
+
+
 def test_downlink_storage_limited_case_caps_rate_and_drains_storage():
+    """Verify storage-limited operation caps removal rate and drains remaining data correctly."""
     debug_print("test_downlink_storage_limited_case_caps_rate_and_drains_storage")
     initial_bits = 300.0
     _, _, storage_log, downlink_log = run_downlink_case(
@@ -302,6 +378,7 @@ def test_downlink_storage_limited_case_caps_rate_and_drains_storage():
 
 
 def test_downlink_auto_receiver_selects_valid_rx_path():
+    """Verify auto receiver selection chooses a valid RX path with nonzero CNR."""
     debug_print("test_downlink_auto_receiver_selects_valid_rx_path")
     _, _, _, downlink_log = run_downlink_case(
         cnr1=0.8,
@@ -317,6 +394,126 @@ def test_downlink_auto_receiver_selects_valid_rx_path():
     assert downlink_log.receiverIndex[-1] == 1
 
 
+def test_downlink_setter_validation_rejects_invalid_inputs():
+    """Check that module setters reject invalid values and preserve prior valid configuration."""
+    debug_print("test_downlink_setter_validation_rejects_invalid_inputs")
+    test_module = downlinkHandling.DownlinkHandling()
+
+    assert test_module.setBitRateRequest(1.0e5)    # [bit/s]
+    assert test_module.setPacketSizeBits(1024.0)   # [bit]
+    assert test_module.setMaxRetransmissions(6)    # [-]
+    assert test_module.setReceiverAntenna(2)       # [-]
+    assert test_module.setRemovalPolicy(REMOVE_DELIVERED_ONLY)
+    test_module.setRequireFullPacket(True)
+
+    with pytest.raises(Exception):
+        test_module.setBitRateRequest(-1.0)                   # [bit/s]
+    with pytest.raises(Exception):
+        test_module.setBitRateRequest(float("nan"))           # [bit/s]
+    with pytest.raises(Exception):
+        test_module.setPacketSizeBits(0.0)                    # [bit]
+    with pytest.raises(Exception):
+        test_module.setPacketSizeBits(float("inf"))           # [bit]
+    with pytest.raises(Exception):
+        test_module.setMaxRetransmissions(0)                  # [-]
+    with pytest.raises(Exception):
+        test_module.setReceiverAntenna(4)                     # [-]
+    with pytest.raises(Exception):
+        test_module.setRemovalPolicy(2)                       # [-]
+
+    assert test_module.getBitRateRequest() == pytest.approx(1.0e5, abs=1e-12)
+    assert test_module.getPacketSizeBits() == pytest.approx(1024.0, abs=1e-12)
+    assert test_module.getMaxRetransmissions() == 6
+    assert test_module.getReceiverAntenna() == 2
+    assert test_module.getRemovalPolicy() == REMOVE_DELIVERED_ONLY
+    assert test_module.getRequireFullPacket() is True
+
+
+def test_downlink_forced_receiver_invalid_path_disables_link():
+    """Verify that forcing an unavailable receiver path yields no selected receiver and zero throughput."""
+    debug_print("test_downlink_forced_receiver_invalid_path_disables_link")
+    _, node_log, _, downlink_log = run_downlink_case(
+        cnr1=0.8,
+        cnr2=0.0,
+        ant_state1=1,
+        ant_state2=2,
+        receiver_index=2,
+        initial_bits=1.0e8
+    )
+
+    assert downlink_log.receiverIndex[-1] == 0
+    assert downlink_log.linkActive[-1] == 0
+    assert downlink_log.storageRemovalRate[-1] == pytest.approx(0.0, abs=1e-12)
+    assert node_log.baudRate[-1] == pytest.approx(0.0, abs=1e-12)
+
+
+def test_downlink_duplicate_storage_message_is_rejected():
+    """Verify duplicate storage message registration is rejected by the module."""
+    debug_print("test_downlink_duplicate_storage_message_is_rejected")
+
+    test_module = downlinkHandling.DownlinkHandling()
+    storage_msg = make_storage_status_msg(100.0, [("DATA", 100.0)])  # [bit]
+
+    assert test_module.addStorageUnitToDownlink(storage_msg) is True
+    assert test_module.addStorageUnitToDownlink(storage_msg) is False
+
+
+def test_downlink_selects_largest_partition_across_storage_messages():
+    """Verify storage selection uses the largest partition across all linked storage status inputs."""
+    debug_print("test_downlink_selects_largest_partition_across_storage_messages")
+
+    unit_task_name = "unitTask"
+    unit_process_name = "unitProcess"
+
+    unit_test_sim = SimulationBaseClass.SimBaseClass()
+    test_proc = unit_test_sim.CreateNewProcess(unit_process_name)
+    test_proc.addTask(unit_test_sim.CreateNewTask(unit_task_name, macros.sec2nano(1.0)))  # [s]
+
+    test_module = downlinkHandling.DownlinkHandling()
+    test_module.ModelTag = "downlink"
+    assert test_module.setBitRateRequest(1.0e5)       # [bit/s]
+    assert test_module.setPacketSizeBits(256.0)       # [bit]
+    assert test_module.setMaxRetransmissions(4)       # [-]
+    assert test_module.setReceiverAntenna(2)          # [-]
+    test_module.setRequireFullPacket(True)            # [-]
+    unit_test_sim.AddModelToTask(unit_task_name, test_module)
+
+    storage_msg_a = make_storage_status_msg(
+        900.0,                                         # [bit]
+        [("A_BIG", 400.0), ("A_SMALL", 100.0)]        # [bit]
+    )
+    storage_msg_b = make_storage_status_msg(
+        2000.0,                                        # [bit]
+        [("B_TOP", 1200.0), ("B_OTHER", 800.0)]       # [bit]
+    )
+    assert test_module.addStorageUnitToDownlink(storage_msg_a)
+    assert test_module.addStorageUnitToDownlink(storage_msg_b)
+
+    link_payload = LinkBudgetMsgPayload.LinkBudgetMsgPayload()
+    link_payload.antennaName1 = "TX_Ant"
+    link_payload.antennaName2 = "RX_Ant"
+    link_payload.antennaState1 = 2                    # [-] TX
+    link_payload.antennaState2 = 1                    # [-] RX
+    link_payload.CNR1 = 0.0                           # [-]
+    link_payload.CNR2 = 20.0                          # [-]
+    link_payload.bandwidth = 1.0e6                    # [Hz]
+    link_payload.frequency = 2.2e9                    # [Hz]
+    link_msg = LinkBudgetMsgPayload.LinkBudgetMsg().write(link_payload)
+    test_module.linkBudgetInMsg.subscribeTo(link_msg)
+
+    downlink_reader = DownlinkHandlingMsgPayload.DownlinkHandlingMsgReader()
+    downlink_reader.subscribeTo(test_module.downlinkOutMsg)
+    downlink_log = downlink_reader.recorder()
+    unit_test_sim.AddModelToTask(unit_task_name, downlink_log)
+
+    unit_test_sim.InitializeSimulation()
+    unit_test_sim.ConfigureStopTime(macros.sec2nano(1.0))    # [s]
+    unit_test_sim.ExecuteSimulation()
+
+    assert downlink_log.availableDataBits[-1] == pytest.approx(1200.0, abs=1e-12)
+    assert downlink_log.dataName[-1] == "B_TOP"
+
+
 if __name__ == "__main__":
     # Allow direct execution:
     # python test_downlinkHandling.py -k test_name -q -s --debug