diff --git a/docs/Design/SoftArchitecture/MG.tex b/docs/Design/SoftArchitecture/MG.tex index 9a529efe..6273bfd8 100644 --- a/docs/Design/SoftArchitecture/MG.tex +++ b/docs/Design/SoftArchitecture/MG.tex @@ -235,6 +235,8 @@ \section{Module Hierarchy} \label{SecMH} actually be implemented. \begin{description} +\item [\refstepcounter{mnum} \mthemnum \label{mHH}:] Hardware-Hiding Module +\item [\refstepcounter{mnum} \mthemnum \label{mM}:] Measurements Module \item [\refstepcounter{mnum} \mthemnum \label{mSmell}:] Smell Module \item [\refstepcounter{mnum} \mthemnum \label{mBR}:] BaseRefactorer Module \item [\refstepcounter{mnum} \mthemnum \label{mMIMR}:] MakeStaticRefactorer Module @@ -272,6 +274,9 @@ \section{Module Hierarchy} \label{SecMH} & ?\\ \midrule +\multirow{3}{0.3\textwidth}{Software Decision Module} & {?}\\ +& Measurements Module\\ +& ?\\ \multirow{3}{0.3\textwidth}{Software Decision Module} & Pylint Analyzer Module\\ & Testing Functionality Module\\ & Measurements Module\\ @@ -397,6 +402,17 @@ \subsection{Software Decision Module} \item[Implemented By:] -- \end{description} +\subsection{Measurements Module} + +\begin{description} +\item[Secrets:] How to measure energy consumption and carbon emissions of a given Python program using the CodeCarbon library, including managing temporary directories for storing output, executing the program, and processing the emissions data from a CSV file. +\item[Services:] Provides functionality for measuring the energy consumption and carbon emissions of a provided code file. This module handles execution, tracking, and data extraction, ensuring that the emissions data is available for further analysis. +\item[Implemented By:] CodeCarbonEnergyMeter +\end{description} + +\subsubsection{Etc.} +\subsubsection{Pylint Analyzer Module} + \subsubsection{Pylint Analyzer Module (\mref{mPyA})} \begin{description} diff --git a/docs/Design/SoftDetailedDes/MIS.tex b/docs/Design/SoftDetailedDes/MIS.tex index 2b0e9cd5..11ba80fa 100644 --- a/docs/Design/SoftDetailedDes/MIS.tex +++ b/docs/Design/SoftDetailedDes/MIS.tex @@ -649,6 +649,110 @@ \subsubsection{Local Functions} \item \textbf{\_generate\_flattened\_access(base\_var: str, access\_chain: list[str])} \\ Generates a flattened dictionary key string by combining elements of an access chain with underscores. \end{itemize} + + + +\section{MIS of Measurements Module} + +\subsection{Module} + +The MeasurementsModule is a module designed to measure and track the carbon emissions generated by executing Python scripts. By leveraging the CodeCarbon library, it allows developers to assess the environmental impact of their code execution. The module runs a specified Python file, tracks the associated carbon emissions during the execution, and logs the results for further analysis. It provides functionality for measuring, logging, and extracting emissions data in a structured manner to help improve energy efficiency in software development. + +\subsection{Uses} + +\begin{itemize} + \item Uses \texttt{CodeCarbon} library for track energy consumption + \item Uses \texttt{TemporaryDirectory} to store temporary files + \item Inherits from \texttt{BaseEnergyMeter} +\end{itemize} + +\subsection{Syntax} + +\subsubsection{Exported Constants} +None + +\subsubsection{Exported Access Programs} + +\begin{center} +\begin{tabular}{|p{3cm}|p{5cm}|p{2cm}|p{3cm}|} +\hline +\textbf{Name} & \textbf{In} & \textbf{Out} & \textbf{Exceptions} \\ +\hline +\texttt{\_\_init\_\_} & \texttt{output\_dir: Path} & None & None \\ +\hline +\texttt{measure\_energy} & \texttt{None} & None & CalledProcessError and FileReading exceptions \\ +\hline +\end{tabular} +\end{center} + +\subsection{Semantics} + +\subsubsection{State Variables} + +\begin{itemize} + \item \textbf{Emissions\_data}: Stores the emissions data extracted from the CSV file generated by CodeCarbon. It is populated after the energy measurement process completes successfully. The value is either a dictionary containing the last row of emissions data or \texttt{None} if no data was extracted due to an error. + +\end{itemize} + +\subsubsection{Environment Variables} + +\begin{itemize} + \item \textbf{TEMP}: Sets the temporary directory location for Windows systems. Used during the CodeCarbon energy measurement process. + \item \textbf{TMPDIR}: Sets the temporary directory location for Unix-based systems. Used during the CodeCarbon energy measurement process. + \item \textbf{Logger}: A logging mechanism that logs various events during the energy measurement process, including errors, completion of measurements, and other key actions. +\end{itemize} + +\subsubsection{Assumptions} + +\begin{itemize} + \item The file at \texttt{file\_path} is a valid Python script. + \item The CodeCarbon tool is properly installed and configured. + \item The \texttt{EmissionsTracker} can successfully execute the Python script specified by \texttt{file\_path}. + \item The emissions data is captured in a CSV format and can be extracted correctly. + \item The temporary directories are correctly set up and accessible during execution. +\end{itemize} + +\subsubsection{Access Routine Semantics} +\paragraph{\texttt{\_\_init\_\_(file\_path: Path)}} +\begin{itemize} + \item \textbf{Transition}: Initializes the \texttt{CodeCarbonEnergyMeter} with the specified file path and logger. It sets up the necessary internal state for energy measurement and prepares the environment. + \item \textbf{Output}: None. + \item \textbf{Exception}: None. +\end{itemize} + +\paragraph{\texttt{measure\_energy()}} +\begin{itemize} + \item \textbf{Transition}: + \begin{itemize} + \item Logs the start of the energy measurement process. + \item Creates a temporary directory to store custom data. + \item Initializes the \texttt{EmissionsTracker} from CodeCarbon. + \item Runs the script specified by \texttt{file\_path} and captures the output. + \item Stops the tracker after execution and stores the emissions data. + \item If available, it extracts the emissions data from the generated CSV file. + \end{itemize} + \item \textbf{Output}: + \begin{itemize} + \item Logs the results of the energy measurement process. + \item Stores the emissions data in \texttt{self.emissions\_data}. + \end{itemize} + \item \textbf{Exception}: + \begin{itemize} + \item Logs an error if the file cannot be executed or if the emissions file is not created. + \item If the emissions data cannot be extracted from the CSV file, logs the issue. + \end{itemize} + \end{itemize} + +\subsubsection{Local Functions} +\paragraph{\texttt{\_extract\_emissions\_csv(csv\_file\_path: Path)}} + + Extracts emissions data from a CSV file generated by CodeCarbon. + \begin{itemize} + \item \textbf{Input}: \texttt{csv\_file\_path} - The path to the CSV file containing emissions data. + \item \textbf{Output}: Returns the last row of emissions data as a dictionary, or \texttt{None} if an error occurs. + \end{itemize} + + \newpage