docs: added top-level docstrings for simulation module

openfasoc/generators/common/simulation/__init__.py

@@ -1,3 +1,11 @@
+"""A common simulation used in OpenFASOC generators.
+
+Sweeps all combinations of given parameters and runs parallel SPICE simulations with different configurations based on the parameters.
+
+Exported functions:
+- `run_simulations()`
+"""
+
 from os import path, makedirs
 from common.simulation.simulation_config import _generate_configs
 from common.simulation.simulation_run import _run_simulations

openfasoc/generators/common/simulation/simulation_config.py

@@ -1,3 +1,17 @@
+"""Sweeps all combinations of given parameters and generates the configurations.
+
+This module is part of the simulation common module. Functions for generating final SPICE files from a template are exported.
+
+Configurations are generated from a template SPICE file that follows the [Mako](https://makotemplates.org) syntax. All possible combinations of the input parameters are swept. The final SPICE files are generated from the template by inserting the parameter combinations. Each file is called a "config" or "configuration."
+
+Exported functions:
+- `_generate_configs()`
+- `_generate_run_parameters()`
+- `_generate_config()`
+
+See individual functions for further documentation.
+"""
+
 from os import path, makedirs
 from shutil import rmtree
 from common.verilog_generation import _generate_file

openfasoc/generators/common/simulation/simulation_run.py

@@ -1,3 +1,17 @@
+"""Runs SPICE simulations in parallel.
+
+This module is part of the simulation common module. Functions for running simulations from SPICE files generated using the `simulation_config` module are exported.
+
+SPICE files are generated by the `simulation_config` module in sub-directories. Each SPICE file is run using the given simulation tool and the outputs and log files are generated in the same sub-directory. The simulations can be run in parallel with a configurable number of concurrent simulations.
+
+Exported functions:
+- `_run_simulations()`
+- `_run_config()`
+- `_threaded_run()`
+
+See individual functions for further documentation.
+"""
+
 from os import path
 from common.simulation.utils import _print_progress
 import time

openfasoc/generators/common/simulation/utils.py

@@ -1,3 +1,14 @@
+"""Utility functions for the simulation common module.
+
+Functions for displaying the simulation progress and formatting the output are exported.
+
+Exported functions:
+- `_print_progress()`
+- `_format_elapsed_time()`
+
+See individual functions for further documentation.
+"""
+
 import time
 
 def _print_progress(total_runs: int, completed_sims: int, failed_sims: int, start_time: int, end: str = '\r'):