[enhancement] Add basic info on model_weight units

posydon/popsyn/norm_pop.py

@@ -307,7 +307,68 @@ def calculate_model_weights(pop_data,
                             M_sim,
                             simulation_parameters,
                             population_parameters):
-    '''reweight each model in the simulation to the requested population'''
+    """Reweight each model in the simulation to the requested population
+
+    Uses the PDF of the simulation and the PDF of the requested population to calculate
+    the weights for each model in the simulation to match the requested population.
+
+    Parameters
+    ----------
+    pop_data : dict
+        Dictionary containing the population data.
+        This needs to contain the following keys:
+        - `S1_mass_i`: initial mass of the primary
+        - `S2_mass_i`: initial mass of the secondary
+        - `orbital_period_i`: initial orbital period
+        - `state_i`: initial state of the system (e.g. 'initially_single_star' for single stars)
+        These are used to calculate the PDF for each model in the simulation.
+
+    M_sim : float
+        Mass of the simulation
+    simulation_parameters : dict
+        Dictionary containing the simulation parameters.
+        This is used to calculate the PDF of the simulation.
+        The parameters in this dictionary are the initial conditions of the population.
+        The following parameters are required to be present in the dictionary:
+        - `primary_mass_scheme`
+        - `primary_mass_min`
+        - `primary_mass_max`
+        - `secondary_mass_scheme`
+        - `secondary_mass_min`
+        - `secondary_mass_max`
+        - `binary_fraction_scheme`
+        - `binary_fraction_const`
+        - `orbital_scheme`
+        - `orbital_period_scheme` or `orbital_separation_scheme` depending on the `orbital_scheme`
+        - `orbital_period_min` and `orbital_period_max` or `orbital_separation_min` and `orbital_separation_max` depending on the `orbital_scheme`
+        - `power_law_slope` if `orbital_period_scheme` is `power_law`
+        - `q_min` and `q_max` if `secondary_mass_scheme` is `flat_mass_ratio`
+
+    population_parameters : dict
+        Dictionary containing the population parameters, which is the requested population to which we want to reweight the simulation. This is used to calculate the PDF of the requested population.
+        The parameters in this dictionary are the initial conditions of the population you want to reweight to.
+        The following parameters are required to be present in the dictionary:
+        - `primary_mass_scheme`
+        - `primary_mass_min`
+        - `primary_mass_max`
+        - `secondary_mass_scheme`
+        - `secondary_mass_min`
+        - `secondary_mass_max`
+        - `binary_fraction_scheme`
+        - `binary_fraction_const`
+        - `orbital_scheme`
+        - `orbital_period_scheme` or `orbital_separation_scheme` depending on the `orbital_scheme`
+        - `orbital_period_min` and `orbital_period_max` or `orbital_separation_min` and `orbital_separation_max` depending on the `orbital_scheme`
+        - `power_law_slope` if `orbital_period_scheme` is `power_law`
+        - `q_min` and `q_max` if `secondary_mass_scheme` is `flat_mass_ratio`
+
+    Returns
+    -------
+    output : ndarray of floats
+        Weights for each model in the simulation to match the requested population
+        This has the units of likelihood of the systems per unit mass (Msun^-1).
+
+    """
 
     f_b_sim = simulation_parameters['binary_fraction_const']
     f_b_pop = population_parameters['binary_fraction_const']

posydon/popsyn/synthetic_population.py

@@ -1882,6 +1882,9 @@ def calculate_model_weights(self, model_weights_identifier, population_parameter
         This method calculates the model weights of each event in the transient population based on the provided model parameters.
         It performs various calculations and stores the results in an HDF5 file at the location '/transients/{transient_name}/weights/{model_weights_identifier}'.
 
+        The calculated model weights represent the probability of an event per Msun
+        formed. Thus, it's units are Msun^{-1}.
+
         Parameters
         ----------
         model_weights_identifier : str
@@ -1891,6 +1894,10 @@ def calculate_model_weights(self, model_weights_identifier, population_parameter
         population_parameters : dict, optional
             Dictionary containing the population parameters. If None, the default population parameters will be used.
 
+        Returns
+        -------
+        pd.DataFrame
+            The model weights of the transient population and have units of Msun^-1.
         """
         if population_parameters is None:
             population_parameters = {'number_of_binaries': 1000000,
@@ -1972,7 +1979,7 @@ def model_weights(self, model_weights_identifier=None):
         """Retrieve the model weights of the transient population.
 
         This method retrieves the model weights of the transient population based on the provided model weights identifier.
-        The model weights are stored in an HDF5 file
+        The model weights are stored in an HDF5 file and have units of Msun^-1.
 
         Parameters
         ----------
@@ -1982,7 +1989,7 @@ def model_weights(self, model_weights_identifier=None):
         Returns
         -------
         pd.DataFrame
-            The model weights of the transient population.
+            The model weights of the transient population in units of Msun^-1.
         """
 
         if model_weights_identifier is None: