Merge pull request #267 from Saransh-cpp/docs

Tidy up docstrings and `ruff --fix`

.pre-commit-config.yaml

@@ -7,9 +7,8 @@ repos:
     rev: 23.12.1
     hooks:
       - id: black
-
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: "v0.1.13"
     hooks:
       - id: ruff
-        args: [--ignore=E741, --exclude=__init__.py]
+        args: [--fix, --ignore=E741, --exclude=__init__.py]

liionpack/netlist_utils.py

@@ -39,7 +39,7 @@ def read_netlist(
         V (float): Initial battery voltage (V).
 
     Returns:
-        pandas.DataFrame:
+        netlist (pandas.DataFrame):
             A netlist of circuit elements with format desc, node1, node2, value.
     """
 
@@ -135,7 +135,7 @@ def setup_circuit(
             "parallel-strings" (default) or "series-groups"
 
     Returns:
-        pandas.DataFrame:
+        netlist (pandas.DataFrame):
             A netlist of circuit elements with format desc, node1, node2, value.
 
     """
@@ -354,9 +354,10 @@ def solve_circuit(netlist):
             A netlist of circuit elements with format desc, node1, node2, value.
 
     Returns:
-        (np.ndarray, np.ndarray):
-        - V_node: Voltages of the voltage elements
-        - I_batt: Currents of the current elements
+        V_node (np.ndarray):
+            Voltages of the voltage elements
+        I_batt (np.ndarray):
+            Currents of the current elements
 
     """
     timer = pybamm.Timer()
@@ -487,9 +488,10 @@ def solve_circuit_vectorized(netlist):
             A netlist of circuit elements with format desc, node1, node2, value.
 
     Returns:
-        (np.ndarray, np.ndarray):
-        - V_node: Voltages of the voltage elements
-        - I_batt: Currents of the current elements
+        V_node (np.ndarray):
+            Voltages of the voltage elements
+        I_batt (np.ndarray):
+            Currents of the current elements
     """
     timer = pybamm.Timer()
 
@@ -621,7 +623,7 @@ def make_lcapy_circuit(netlist):
             A netlist of circuit elements with format. desc, node1, node2, value.
 
     Returns:
-        lcapy.Circuit:
+        cct (lcapy.Circuit):
             The Circuit class is used for describing networks using netlists.
             Despite the name, it does not require a closed path.
 
@@ -714,9 +716,6 @@ def power_loss(netlist, include_Ri=False):
             Default is False. If True the internal resistance of the batteries
             is included
 
-    Returns:
-        None
-
     """
     V_node, I_batt = lp.solve_circuit_vectorized(netlist)
     R_map = netlist["desc"].str.find("R") > -1
@@ -751,10 +750,6 @@ def write_netlist(netlist, filename):
         netlist (pandas.DataFrame):
             A netlist of circuit elements with format desc, node1, node2, value.
 
-    Returns:
-        None
-
-
     """
     lines = ["* " + filename]
     for i, r in netlist.iterrows():

liionpack/protocols.py

@@ -14,7 +14,7 @@ def generate_protocol_from_experiment(experiment, flatten=True):
             list of lists for each operating command.
 
     Returns:
-        list:
+        protocol (list):
             a sequence of terminal currents to apply at each timestep
 
     """

liionpack/sim_utils.py

@@ -45,8 +45,10 @@ def update_init_conc(param, SoC=None, update=True):
             Update the initial concentrations in place if True
 
     Returns:
-        c_s_n_init, c_s_p_init (float):
-            initial concentrations in negative and positive particles
+        c_s_n_init (float):
+            initial concentrations in negative particles.
+        c_s_p_init (float):
+            initial concentrations in positive particles.
     """
     c_n_max = param["Maximum concentration in negative electrode [mol.m-3]"]
     c_p_max = param["Maximum concentration in positive electrode [mol.m-3]"]

liionpack/simulations.py

@@ -15,7 +15,7 @@ def basic_simulation(parameter_values=None):
             The default is None.
 
     Returns:
-        pybamm.Simulation:
+        sim (pybamm.Simulation):
             A simulation that can be solved individually or passed into the
             liionpack solve method
 
@@ -51,7 +51,7 @@ def thermal_simulation(parameter_values=None):
             The default is None.
 
     Returns:
-        pybamm.Simulation:
+        sim (pybamm.Simulation):
             A simulation that can be solved individually or passed into the
             liionpack solve method
 
@@ -101,7 +101,7 @@ def thermal_external(parameter_values=None):
             The default is None.
 
     Returns:
-        pybamm.Simulation:
+        sim (pybamm.Simulation):
             A simulation that can be solved individually or passed into the
             liionpack solve method
 

liionpack/utils.py

@@ -17,7 +17,7 @@ def interp_current(df):
             construct an interpolant function
 
     Returns:
-        function:
+        f (function):
             interpolant function of total cell current with time.
 
     """
@@ -38,7 +38,7 @@ def _convert_dict_to_list_of_dict(inputs_dict):
             arrays of input values for each battery.
 
     Returns:
-        list:
+        dicts (list):
             individual dictionaries containing one element for each key
 
     """
@@ -67,7 +67,7 @@ def build_inputs_dict(I_batt, inputs, updated_inputs):
             of variable values for each battery.
 
     Returns:
-        list:
+        inputs_dict (list):
             each element of the list is an inputs dictionary corresponding to each
             battery.
 
@@ -93,7 +93,7 @@ def add_events_to_model(model):
             The PyBaMM model to solve.
 
     Returns:
-        pybamm.lithium_ion.BaseModel:
+        model (pybamm.lithium_ion.BaseModel):
             The PyBaMM model to solve with events added as variables.
 
     """
@@ -106,16 +106,14 @@ def save_to_csv(output, path="./csv-results"):
     """
     Save simulation output to a CSV file for each output variable.
 
-    Parameters
-    ----------
-    output : dict
-        Simulation output dictionary.
-    path : str
-        Folder path for saving the CSV files. Default path is a folder named
-        `csv-results` in the current directory.
+    Args:
+        output (dict):
+            Simulation output dictionary.
+        path (str):
+            Folder path for saving the CSV files. Default path is a folder named
+            `csv-results` in the current directory.
 
-    Returns
-    -------
+    Returns:
         CSV files written to the specified path. Each file represents a single
         output variable.
     """
@@ -135,16 +133,14 @@ def save_to_npy(output, path="./npy-results"):
     Save simulation output to NumPy `.npy` files where each file represents an
     output variable.
 
-    Parameters
-    ----------
-    output : dict
-        Simulation output dictionary.
-    path : str
-        Folder path where the `.npy` files are saved. Default path is a folder
-        named `npy-results` located in the current directory.
+    Args:
+        output (dict):
+            Simulation output dictionary.
+        path (str):
+            Folder path where the `.npy` files are saved. Default path is a folder
+            named `npy-results` located in the current directory.
 
-    Returns
-    -------
+    Returns:
         NumPy `.npy` files written to the specified path. Each file represents
         a single output variable.
     """
@@ -165,16 +161,14 @@ def save_to_npzcomp(output, path="."):
     file is a dictionary-like object where each key represents a simulation
     output variable.
 
-    Parameters
-    ----------
-    output : dict
-        Simulation output dictionary.
-    path : str
-        Path where the `output.npz` file is saved. Default path is the current
-        directory.
+    Args:
+        output (dict):
+            Simulation output dictionary.
+        path (str):
+            Path where the `output.npz` file is saved. Default path is the current
+            directory.
 
-    Returns
-    -------
+    Returns:
         A compressed NumPy `.npz` file named `output.npz` written to the
         specified path. The file is a dictionary-like object where each key
         has the same name as the simulation output variable.