From e8a3a8d03760b51c8852048b658e8e43ec5511c6 Mon Sep 17 00:00:00 2001 From: Harsh Khandeparkar Date: Thu, 7 Sep 2023 21:48:46 +0530 Subject: [PATCH] docs: added top-level docstrings for simulation module --- openfasoc/generators/common/simulation/__init__.py | 8 ++++++++ .../common/simulation/simulation_config.py | 14 ++++++++++++++ .../generators/common/simulation/simulation_run.py | 14 ++++++++++++++ openfasoc/generators/common/simulation/utils.py | 11 +++++++++++ 4 files changed, 47 insertions(+) diff --git a/openfasoc/generators/common/simulation/__init__.py b/openfasoc/generators/common/simulation/__init__.py index caabc58f8..90150528e 100644 --- a/openfasoc/generators/common/simulation/__init__.py +++ b/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 diff --git a/openfasoc/generators/common/simulation/simulation_config.py b/openfasoc/generators/common/simulation/simulation_config.py index e137c44b0..135d8d070 100644 --- a/openfasoc/generators/common/simulation/simulation_config.py +++ b/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 diff --git a/openfasoc/generators/common/simulation/simulation_run.py b/openfasoc/generators/common/simulation/simulation_run.py index 6ab41fdfa..df5fb39dd 100644 --- a/openfasoc/generators/common/simulation/simulation_run.py +++ b/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 diff --git a/openfasoc/generators/common/simulation/utils.py b/openfasoc/generators/common/simulation/utils.py index 375e13099..7a028fcdf 100644 --- a/openfasoc/generators/common/simulation/utils.py +++ b/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'):