doc update

Author: shubhvjain

codegreen_core/tools/carbon_emission.py

@@ -6,7 +6,6 @@
 
 from .carbon_intensity import compute_ci
 
-
 def compute_ce(
     server: dict,
     start_time: datetime,
@@ -46,7 +45,6 @@ def compute_ce(
     ce_total, ce_df = compute_ce_from_energy(server, ci_ts)
     return ce_total, ce_df
 
-
 def _compute_energy_used(
     runtime_minutes,
     number_core,

codegreen_core/tools/carbon_intensity.py

@@ -118,13 +118,24 @@ def _calculate_ci_from_energy_mix(energy_mix):
 
 def compute_ci(country: str, start_time: datetime, end_time: datetime) -> pd.DataFrame:
     """
-    Computes carbon intensity data for a given country and time period.
+    Computes the carbon intensity (CI) for a given country and time period.
 
-    If energy data is available, the carbon intensity is calculated from actual energy data for the specified  time range.
-    If energy data is not available for the country, a default carbon intensity value is used instead.
-    The default CI values for all countries are stored in utilities/ci_default_values.csv.
+    This function determines the energy data source for the country. 
+    - If energy data is available (e.g., from ENTSOE), it calculates CI using actual energy data.
+    - If energy data is unavailable, it uses default CI values from `ci_default_values.csv` for the country.
+
+    :param country: The 2 letter country code.
+    :type country: str
+    :param start_time: The start of the time range for which CI is computed.
+    :type start_time: datetime
+    :param end_time: The end of the time range for which CI is computed.
+    :type end_time: datetime
+
+    :returns: A pandas DataFrame containing timestamps (`startTimeUTC`) and corresponding carbon intensity values.
+    :rtype: pd.DataFrame
 
     """
+
     if not isinstance(country, str):
         raise ValueError("Invalid country")
 
@@ -133,6 +144,10 @@ def compute_ci(country: str, start_time: datetime, end_time: datetime) -> pd.Dat
 
     if not isinstance(end_time, datetime):
         raise ValueError("Invalid end_time")
+    
+    if start_time >= end_time:
+        raise ValueError("start_time must be before end_time")
+    
 
     e_source = get_country_energy_source(country)
     if e_source == "ENTSOE":
@@ -190,6 +205,7 @@ def compute_ci_from_energy(
         - `Nuclear` (float): Base carbon intensity value for nuclear energy.
         - `Solar` (float): Base carbon intensity value for solar energy.
         - `Wind` (float): Base carbon intensity value for wind energy.
+    
     """
 
     if not isinstance(energy_data, pd.DataFrame):

codegreen_core/tools/loadshift_location.py

@@ -11,10 +11,7 @@ def predict_optimal_location_now(
     percent_renewable: int,
     hard_finish_date: datetime,
 ) -> tuple:
-    """
-    Given a list of countries, returns the best location where a computation can be run based on the input criteria
-    """
-    print()
+    # Given a list of countries, returns the best location where a computation can be run based on the input criteria
     # first get data
     start_time = datetime.now()
     forecast_data = (
@@ -45,9 +42,8 @@ def predict_optimal_location(
     hard_finish_date,
     request_date=None,
 ):
-    """
-    Determines the optimal location and time  to run a computation using  energy data of the selected locations
-    """
+    
+    #Determines the optimal location and time  to run a computation using  energy data of the selected locations
     ## obtain the optimal start time for each country
     best_values = {}
     current_best = -1

codegreen_core/tools/loadshift_time.py

@@ -16,7 +16,6 @@
 
 # ========= the main methods  ============
 
-
 def _get_energy_data(country, start, end):
     """
     Get energy data and check if it must be cached based on the options set
@@ -129,7 +128,7 @@ def predict_optimal_time(
     request_time: datetime = None,
 ) -> tuple:
     """
-    Predicts the optimal time window to run a task based in energy data, run time estimates and renewable energy target.
+    Predicts the optimal time window to run a task within the given energy data time frame the run time estimate .
 
     :param energy_data: A DataFrame containing the energy data including startTimeUTC, totalRenewable,total,percent_renewable,posix_timestamp
     :param estimated_runtime_hours: The estimated runtime in hours

docs/index.rst

@@ -14,6 +14,7 @@ Welcome to codegreen_core's documentation!
    features
    installation
    setup
+   Tutorial <https://github.com/codegreen-framework/codegreen-core/blob/main/docs/Tutorials.ipynb>
    api 
    status
    methodology

docs/methodology.rst

@@ -36,11 +36,10 @@ One challenge with the carbon intensity calculation is that the values can vary
 When energy generation data is not available for a country, the average values of Carbon Intensity is used. The source of this data is Carbon Footprint Ltd [8]
 
 
-
 Carbon emission of a job
 -------------------------
 
-**The Methodology for calculating carbon emissions** (Based on [7])
+The Methodology for calculating carbon emissions is based on [7]
 
 Carbon emission of a job depends on 2 factors : Energy consumed by the hardware to run the computation and the emissions generated to produce this energy. The unit used is CO2e or Carbon dioxide equivalent.
 
@@ -57,4 +56,3 @@ Carbon emission of a job depends on 2 factors : Energy consumed by the hardware
 
 - Emissions related to the production of the energy : represented by the Carbon Intensity of the energy mix during that period. Already implemented above
 - The result is Carbon emission in CO2e
-

docs/references.rst

@@ -4,8 +4,8 @@ References
 This page lists out all the references to external sources used in the documentation.
 
 
-- [1] J. Malmodin, N. Lövehagen, P. Bergmark, and D. Lundén, ‘ICT sector electricity consumption and greenhouse gas emissions – 2020 outcome’, Telecommunications Policy, vol. 48, no. 3, p. 102701, Apr. 2024, doi: 10.1016/j.telpol.2023.102701.
-- [2] E. Strubell, A. Ganesh, and A. McCallum, ‘Energy and Policy Considerations for Deep Learning in NLP’, Jun. 05, 2019, arXiv: arXiv:1906.02243. Accessed: Oct. 11, 2024. [Online]. Available: http://arxiv.org/abs/1906.02243
+- [1] J. Malmodin, N. Lövehagen, P. Bergmark, and D. Lundén, 'ICT sector electricity consumption and greenhouse gas emissions - 2020 outcome', Telecommunications Policy, vol. 48, no. 3, p. 102701, Apr. 2024, doi: 10.1016/j.telpol.2023.102701.
+- [2] E. Strubell, A. Ganesh, and A. McCallum, 'Energy and Policy Considerations for Deep Learning in NLP', Jun. 05, 2019, arXiv: arXiv:1906.02243. Accessed: Oct. 11, 2024. [Online]. Available: http://arxiv.org/abs/1906.02243
 - [3] Carbon intensity of electricity generation https://ourworldindata.org/grapher/carbon-intensity-electricity (Accessed 11-10-24)
 - [4] N. Scarlat, M. Prussi, and M. Padella, “Quantification of the carbon intensity of electricity produced and used in Europe,” Applied Energy, vol. 305. Elsevier BV, p. 117901, Jan. 2022. doi: 10.1016/j.apenergy.2021.117901.
 - [5] Schlömer S., T. Bruckner, L. Fulton, E. Hertwich, A. McKinnon, D. Perczyk, J. Roy, R. Schaeffer, R. Sims, P. Smith, and R. Wiser, 2014: Annex III: Technology-specific cost and performance parameters. In: Climate Change 2014: Mitigation of Climate Change. Contribution of Working Group III to the Fifth Assessment Report of the Intergovernmental Panel on Climate Change [Edenhofer, O., R. Pichs-Madruga, Y. Sokona, E. Farahani, S. Kadner, K. Seyboth, A. Adler, I. Baum, S. Brunner, P. Eickemeier, B. Kriemann, J. Savolainen, S. Schlömer, C. von Stechow, T. Zwickel and J.C. Minx (eds.)]. Cambridge University Press, Cambridge, United Kingdom and New York, NY, USA. (https://www.ipcc.ch/site/assets/uploads/2018/02/ipcc_wg3_ar5_annex-iii.pdf#page=7) (Accessed 11-10-24)