Add docstrings, block comments and TODOs.

tardis/montecarlo/tests/test_cmontecarlo.py

@@ -1,3 +1,46 @@
+"""
+Unit tests for methods in `tardis/montecarlo/src/cmontecarlo.c`.
+* `ctypes` library is used to wrap C methods and expose them to python.
+
+
+Probable Reasons for Failing Tests:
+-----------------------------------
+
+1. Change made in C struct declarations:
+  - Reflect the changes done in C structs, into Python counterparts.
+  - Check **tardis/montecarlo/struct.py**.
+
+2. Return type of any method changed:
+  - Modify the `restype` parameter in the test method here.
+  - For example:
+        ```
+        cmontecarlo_methods.rpacket_doppler_factor.restype = c_double
+        ```
+
+3. Underlying logic modified:
+  - Check whether the changes made in C method are logically correct.
+  - If the changes made were correct and necessary, update the corresponding
+    test case.
+
+
+General Test Design Procedure:
+------------------------------
+
+Please follow this design procedure while adding a new test:
+
+1. Parametrization as per desire of code coverage.
+  - C tests have different flows controlled by conditional statements.
+    Parameters checked in conditions can be provided in different testcases.
+  - Keep consistency with variable names as (in order):
+    - `packet_params`
+    - `model_params`
+    - `expected_params` (`expected` if only one value to be asserted.)
+
+2. Test Method body:
+  - Keep name as `test_` + `(name of C method)`.
+  - Refer to method `test_rpacket_doppler_factor` below for description.
+"""
+
 import os
 import pytest
 from ctypes import CDLL, byref, c_uint, c_int64, c_double, c_ulong
@@ -6,15 +49,19 @@
 from tardis import __path__ as path
 from tardis.montecarlo.struct import RPacket, StorageModel, RKState
 
+# Wrap the shared object containing tests for C methods, written in C.
+# TODO: Shift all tests here in Python and completely remove this test design.
 test_path = os.path.join(path[0], 'montecarlo', 'test_montecarlo.so')
 cmontecarlo_tests = CDLL(test_path)
 
+# Wrap the shared object containing C methods, which are tested here.
 cmontecarlo_filepath = os.path.join(path[0], 'montecarlo', 'montecarlo.so')
 cmontecarlo_methods = CDLL(cmontecarlo_filepath)
 
 
 @pytest.fixture(scope="function")
 def packet():
+    """Fixture to return `RPacket` object with default params initialized."""
     packet_default = {
         'nu': 0.4,
         'mu': 0.3,
@@ -37,6 +84,7 @@ def packet():
 
 @pytest.fixture(scope="function")
 def model():
+    """Fixture to return `StorageModel` object with default params initialized."""
     model_default = {
         'last_line_interaction_in_id': (c_int64 * 2)(*([0] * 2)),
         'last_line_interaction_shell_id': (c_int64 * 2)(*([0] * 2)),
@@ -97,6 +145,7 @@ def model():
 
 @pytest.fixture(scope="function")
 def mt_state():
+    """Fixture to return `RKState` object with default params initialized."""
     mt_state_default = {
         'key': (c_ulong * 624)(*([0] * 624)),
         'pos': 0,
@@ -115,13 +164,20 @@ def mt_state():
       1.0003117541351274)]
 )
 def test_rpacket_doppler_factor(packet_params, model_params, expected, packet, model):
+    # Set the params from test cases here
     packet.mu = packet_params['mu']
     packet.r = packet_params['r']
     model.inverse_time_explosion = model_params['inverse_time_explosion']
 
+    # Perform any other setups just before this, they can be additional calls
+    # to other methods or introduction of some temporary variables
+
+    # Set `restype` attribute if returned quantity is used
     cmontecarlo_methods.rpacket_doppler_factor.restype = c_double
+    # Call the C method (make sure to pass quantities as `ctypes` data types)
     obtained = cmontecarlo_methods.rpacket_doppler_factor(byref(packet), byref(model))
 
+    # Perform required assertions
     assert_almost_equal(obtained, expected)
 
 
@@ -246,6 +302,7 @@ def test_montecarlo_line_scatter(packet_params, expected_params, packet, model,
     assert_almost_equal(packet.next_line_id, expected_params['next_line_id'])
 
 
+# TODO: redesign subsequent tests according to tests written above.
 def test_move_packet_across_shell_boundary():
     assert cmontecarlo_tests.test_move_packet_across_shell_boundary()