Updating documentation for classes and functions (#153)

* documented music_box.py

* documented music_box_conditions.py

* documented evolving conditions

* documented box model options

* documented reaction list

* documented reactions

* documented species list

src/acom_music_box/music_box.py

@@ -58,10 +58,13 @@ def add_evolving_condition(self, time_point, conditions):
 
     def generateConfig(self, directory):
         """
-        Generate configuration JSON for the box model simulation.
+        Generate configuration JSON for the box model simulation and writes it to files in the specified directory.
+
+        Args:
+            directory (str): The directory where the configuration files will be written.
 
         Returns:
-        tuple: A tuple containing the species configuration JSON and the reaction configuration JSON.
+            None
         """
         output_path = "./src/configs/" + directory
 
@@ -411,10 +414,20 @@ def create_solver(self, path_to_config):
 
     def solve(self, path_to_output = None):
         """
-        TODO: Solve the box model simulation.
+        Solves the box model simulation and optionally writes the output to a file.
+
+        This function runs the box model simulation using the current settings and 
+        conditions. If a path is provided, it writes the output of the simulation to 
+        the specified file.
+
+        Args:
+            path_to_output (str, optional): The path to the file where the output will 
+            be written. If None, no output file is created. Defaults to None.
+
+        Returns:
+            list: A 2D list where each inner list represents the results of the simulation 
+            at a specific time step.
         """
-        # TODO: Implement the logic to solve the box model simulation.
-        # Update the internal state of the BoxModel instance to reflect the simulation results.
 
         #sets up initial conditions to be current conditions
         curr_conditions = self.initial_conditions
@@ -523,9 +536,21 @@ def solve(self, path_to_output = None):
 
     def readFromUIJson(self, path_to_json):
         """
-        TODO: Read the box model configuration from json and sets config
+        Reads and parses a JSON file from the MusicBox Interactive UI to set up the box model simulation.
+
+        This function takes the path to a JSON file, reads the file, and parses the JSON 
+        to set up the box model simulation.
+
+        Args:
+            path_to_json (str): The path to the JSON file from the UI.
+
+        Returns:
+            None
+
+        Raises:
+            ValueError: If the JSON file cannot be read or parsed.
         """
-        # TODO: Implement the logic to update the box model config using a json.
+
 
         with open(path_to_json, 'r') as json_file:
             data = json.load(json_file)
@@ -547,9 +572,18 @@ def readFromUIJson(self, path_to_json):
 
     def readFromUIJsonString(self, data):
         """
-        TODO: Read the box model configuration from json and sets config
+        Reads and parses a JSON string from the MusicBox Interactive UI to set up the box model simulation.
+
+        Args:
+            json_string (str): The JSON string from the UI.
+
+        Returns:
+            None
+
+        Raises:
+            ValueError: If the JSON string cannot be parsed.
         """
-        # TODO: Implement the logic to update the box model config using a json.
+
 
         # Set box model options
         self.box_model_options = BoxModelOptions.from_UI_JSON(data)
@@ -586,13 +620,42 @@ def readConditionsFromJson(self, path_to_json):
 
 
     def speciesOrdering(self):
+        """
+        Retrieves the ordering of species used in the solver.
+
+        This function calls the `species_ordering` function from the `musica` module, 
+        passing the solver instance from the current object.
+
+        Returns:
+            dict: The ordered dictionary of species used in the solver.
+        """
         return musica.species_ordering(self.solver)
 
     def userDefinedReactionRates(self):
-        return musica.user_defined_reaction_rates(self.solver)
-
+        """
+        Retrieves the user-defined reaction rates from the solver.
+
+        This function calls the `user_defined_reaction_rates` function from the `musica` module, 
+        passing the solver instance from the current object.
+
+        Returns:
+            dict: The dictionary of user-defined reaction rates used in the solver.
+        """
     @classmethod
     def order_reaction_rates(self, curr_conditions, rate_constant_ordering):
+        """
+        Orders the reaction rates based on the provided ordering.
+
+        This function takes the current conditions and a specified ordering for the rate constants, 
+        and reorders the reaction rates accordingly.
+
+        Args:
+            rate_constants (dict): A dictionary of rate constants.
+            rate_constant_ordering (dict): A dictionary that maps rate constant keys to indices for ordering.
+
+        Returns:
+            list: An ordered list of rate constants.
+        """
         rate_constants = {}
         for rate in curr_conditions.reaction_rates:
 

src/acom_music_box/music_box_conditions.py

@@ -37,13 +37,18 @@ def __init__(self, pressure, temperature, species_concentrations=None, reaction_
     @classmethod
     def from_UI_JSON(cls, UI_JSON, species_list, reaction_list):
         """
-        Create a new instance of the Conditions class from a JSON object.
+        Creates an instance of the class from a UI JSON object.
+
+        This class method takes a UI JSON object, a species list, and a reaction list, 
+        and uses them to create a new instance of the class.
 
         Args:
-            UI_JSON (dict): A JSON object representing the conditions.
+            UI_JSON (dict): The UI JSON object containing the initial conditions and settings.
+            species_list (SpeciesList): A SpeciesList containing the species involved in the simulation.
+            reaction_list (ReactionList): A ReactionList containing the reactions involved in the simulation.
 
         Returns:
-            Conditions: A new instance of the Conditions class.
+            object: An instance of the Conditions class with the settings from the UI JSON object.
         """
         pressure = convert_pressure(UI_JSON['conditions']['environmental conditions']['pressure'], 'initial value')
 
@@ -79,6 +84,21 @@ def from_UI_JSON(cls, UI_JSON, species_list, reaction_list):
 
     @classmethod
     def from_config_JSON(cls, path_to_json, config_JSON, species_list, reaction_list):
+        """
+        Creates an instance of the class from a configuration JSON object.
+
+        This class method takes a path to a JSON file, a configuration JSON object, a species list, 
+        and a reaction list, and uses them to create a new instance of the class.
+
+        Args:
+            path_to_json (str): The path to the JSON file containing the initial conditions and settings.
+            config_JSON (dict): The configuration JSON object containing the initial conditions and settings.
+            species_list (SpeciesList): A SpeciesList containing the species involved in the simulation.
+            reaction_list (ReactionList): A ReactionList containing the reactions involved in the simulation.
+
+        Returns:
+            object: An instance of the Conditions class with the settings from the configuration JSON object.
+        """
         pressure = convert_pressure(config_JSON['environmental conditions']['pressure'], 'initial value')
 
         temperature = convert_temperature(config_JSON['environmental conditions']['temperature'], 'initial value')
@@ -107,8 +127,6 @@ def from_config_JSON(cls, path_to_json, config_JSON, species_list, reaction_list
             if not any(conc.species.name == species.name for conc in species_concentrations):
                 species_concentrations.append(SpeciesConcentration(species, 0)) 
 
-
-        #TODO: may or may not be necessary
         # Set initial reaction rates
 
         for reaction in reaction_list.reactions:
@@ -121,6 +139,19 @@ def from_config_JSON(cls, path_to_json, config_JSON, species_list, reaction_list
 
     @classmethod
     def read_initial_rates_from_file(cls, file_path, reaction_list):
+        """
+        Reads initial reaction rates from a file.
+
+        This class method takes a file path and a ReactionList, reads the file, and 
+        sets the initial reaction rates based on the contents of the file.
+
+        Args:
+            file_path (str): The path to the file containing the initial reaction rates.
+            reaction_list (ReactionList): A ReactionList containing the reactions involved in the simulation.
+
+        Returns:
+            list: A list where each element represents the initial rate of a reaction.
+        """
 
         reaction_rates = []
 

src/acom_music_box/music_box_evolving_conditions.py

@@ -17,11 +17,12 @@ class EvolvingConditions:
 
     def __init__(self, headers=None, times=None, conditions=None):
         """
-        Initializes a new instance of the EvolvingConditions class.
+        Initializes an instance of the EvolvingConditions class.
 
         Args:
-            time (List[float]): A list of time points. Default is an empty list.
-            conditions (List[Conditions]): A list of associated conditions. Default is an empty list.
+            headers (list, optional): A list of headers for the data. Defaults to None.
+            times (list, optional): A list of times at which the conditions are recorded. Defaults to None.
+            conditions (list, optional): A list of conditions at each time point. Defaults to None.
         """
         self.headers = headers if headers is not None else []
         self.times = times if times is not None else []
@@ -33,7 +34,7 @@ def from_UI_JSON(cls, UI_JSON, species_list, reaction_list):
         Create a new instance of the EvolvingConditions class from a JSON object.
 
         Args:
-            UI_JSON (dict): A JSON object representing the evolving conditions.
+        UI_JSON (dict): A JSON object representing the evolving conditions.
 
         Returns:
             EvolvingConditions: A new instance of the EvolvingConditions class.
@@ -86,8 +87,22 @@ def from_UI_JSON(cls, UI_JSON, species_list, reaction_list):
 
     @classmethod
     def from_config_JSON(cls, path_to_json ,config_JSON, species_list, reaction_list):
-        # Initialize empty lists for times and conditions
-
+        """
+        Creates an instance of the EvolvingConditions class from a configuration JSON object.
+
+        This class method takes a path to a JSON file, a configuration JSON object, a SpeciesList, 
+        and a ReactionList, and uses them to create a new instance of the EvolvingConditions class.
+
+        Args:
+            path_to_json (str): The path to the JSON file containing the initial conditions and settings.
+            config_JSON (dict): The configuration JSON object containing the initial conditions and settings.
+            species_list (SpeciesList): A SpeciesList containing the species involved in the simulation.
+            reaction_list (ReactionList): A ReactionList containing the reactions involved in the simulation.
+
+        Returns:
+            EvolvingConditions: An instance of the EvolvingConditions class with the settings from the configuration JSON object.
+        """
+
 
         evolving_conditions = EvolvingConditions()
 
@@ -186,4 +201,14 @@ def read_conditions_from_file(cls, file_path, species_list, reaction_list):
 
     #allows len overload for this class
     def __len__(self):
+        """
+        Returns the number of time points in the EvolvingConditions instance.
+
+        This method is a part of Python's data model methods and allows the built-in 
+        `len()` function to work with an instance of the EvolvingConditions class. 
+        It should return the number of time points for which conditions are recorded.
+
+        Returns:
+            int: The number of time points in the EvolvingConditions instance.
+        """
         return len(self.times)

src/acom_music_box/music_box_model_options.py

@@ -30,10 +30,10 @@ def __init__(self, chem_step_time, output_step_time, simulation_length, grid="bo
     @classmethod
     def from_UI_JSON(cls, UI_JSON):
         """
-        Create a new instance of the BoxModelOptions class from a JSON object.
+        Create a new instance of the BoxModelOptions class from a JSON object from the MusicBox Interactive UI.
 
         Args:
-            UI_JSON (dict): A JSON object representing the user interface options.
+            UI_JSON (dict): A JSON object representing the box model options from the user interface options.
 
         Returns:
             BoxModelOptions: A new instance of the BoxModelOptions class.
@@ -49,6 +49,15 @@ def from_UI_JSON(cls, UI_JSON):
 
     @classmethod
     def from_config_JSON(cls, config_JSON):
+        """
+        Create a new instance of the BoxModelOptions class from a JSON object from a configuration JSON.
+
+        Args:
+            UI_JSON (dict): A JSON object representing box model options.
+
+        Returns:
+            BoxModelOptions: A new instance of the BoxModelOptions class.
+        """
 
         chem_step_time = convert_time(config_JSON['box model options'], 'chemistry time step')
         output_step_time = convert_time(config_JSON['box model options'], 'output time step')