Skip to content

Commit ebcd4e8

Browse files
shubhvjainshubhvjain
committed
modified docs
1 parent 4b0177e commit ebcd4e8

File tree

6 files changed

+222
-106
lines changed

6 files changed

+222
-106
lines changed

‎docs/api.rst

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
codegreen_core API
2+
===================
3+
4+
5+
Package Organization
6+
---------------------
7+
8+
.. image:: _static/modules.png
9+
:alt: modules
10+
:width: 400px
11+
:align: center
12+
13+
14+
The package is divided into two main sub packages: `data`` and `tools`. (There is also an additional module, `utilities`, which provides helper methods that support other modules.)
15+
16+
The `data` sub package contains methods for fetching energy production data. This package relies on external data sources to retrieve this information, which is then processed to make it usable by other components of the package. For more details and a complete API , see the data module documentation.
17+
18+
The `tools` sub package provides a variety of tools, including:
19+
20+
- Carbon intensity calculator
21+
- Carbon emission calculator
22+
- Optimal time-shifting predictor
23+
- Optimal location-shifting predictor
24+
25+
26+
Example : Calculating optimal time for a computational task
27+
-------------------------------------------------------------
28+
Assuming all the above steps are done, you can now calculate the optimal starting time for a computations.
29+
30+
.. code-block:: python
31+
32+
from datetime import datetime,timedelta
33+
from codegreen_core.tools.loadshift_time import predict_now
34+
35+
country_code = "DK"
36+
est_runtime_hour = 10
37+
est_runtime_min = 0
38+
now = datetime.now()
39+
hard_finish_date = now + timedelta(days=1)
40+
criteria = "percent_renewable"
41+
per_renewable = 50
42+
43+
time = predict_now(country_code,
44+
est_runtime_hour,
45+
est_runtime_min,
46+
hard_finish_date,
47+
criteria,
48+
per_renewable)
49+
# (1728640800.0, <Message.OPTIMAL_TIME: 'OPTIMAL_TIME'>, 76.9090909090909)
50+
51+
52+
53+
The core package contains 2 main module :
54+
- `data` : To fetch energy data for a country
55+
- `tools` : To calculate various quantities like Optimal computation time, carbon intensity etc.
56+
57+
58+
`data` module
59+
--------------
60+
61+
.. automodule:: codegreen_core.data
62+
:members:
63+
64+
65+
`tools` module
66+
---------------
67+
68+
.. automodule:: codegreen_core.tools
69+
:members:
70+
71+
72+
.. automodule:: codegreen_core.tools.carbon_intensity
73+
:members:
74+
75+
76+
.. automodule:: codegreen_core.tools.carbon_emission
77+
:members:
78+
79+
80+
.. automodule:: codegreen_core.tools.loadshift_time
81+
:members:
82+
83+
84+
.. automodule:: codegreen_core.tools.loadshift_location
85+
:members:

‎docs/data.rst

Lines changed: 0 additions & 27 deletions
This file was deleted.

‎docs/getting_started.rst

Lines changed: 119 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -1,97 +1,159 @@
11
.. getting_started:
22
33
4-
Getting Started
5-
===============
4+
How to use codegreen
5+
=====================
66

7-
Welcome to the guide for getting started with `codegreen_core`. This document provides installation instructions and the initial steps required to get the package up and running. It also outlines the package structure, which will help you choose the appropriate tools based on your needs.
7+
Welcome to the guide for getting started with the `codegreen` framework.
8+
There are four main ways to setup and use Codegreen based on your requirements.
9+
This document describes in detail the steps involved in each method.
810

9-
Installation
10-
-------------
11+
The four ways to use codegreen:
1112

12-
Using pip :
13+
1. Using `codegreen.world`
14+
2. Setting up and using the `codegreen_core` package
15+
3. Setting up your own web server
16+
4. Deploying the web service using the docker container
17+
18+
19+
Using codegreen.world
20+
----------------------
21+
22+
The simplest and fastest way to use Codegreen is through our web service.
23+
This is ideal for beginners and new users looking for an easy way to reduce the carbon emissions of their computations.
24+
25+
1. Visit `www.codegreen.world <https://www.codegreen.world>`_
26+
2. Create and account and log in
27+
3. Generate an API token for your location and server details
28+
4. Use the "Predict Optimal Time" form to get a time prediction for starting a computation in your selected location and server.
29+
30+
31+
Additionally, we provide `codegreen_client`, a Python package that can automatically start your Python scripts at the optimal time. Please refer to for installation and setup guide for more details.
32+
33+
34+
The web service also includes a dashboard where you can track how much carbon emission you have saved in each registered location.
35+
36+
37+
Installing the `codegreen_core` package
38+
-----------------------------------------
39+
40+
The `codegreen_core` Python package contains all the core functionalities of the Codegreen framework and can be used as a standalone tool.
41+
This is ideal for researchers and developers who need to gather energy data for a country and perform calculations such as carbon intensity analysis.
42+
43+
**Step 1: Installation**
44+
45+
You can install the package using pip :
1346

1447
.. code-block:: python
1548
1649
pip install codegreen_core
1750
18-
You can also use clone the git repository and install the package :
51+
Alternatively, you can clone the Git repository and install the package manually:
1952

2053
.. code-block:: bash
2154
2255
git clone https://github.com/bionetslab/codegreen-core.git
2356
pip install -e .
2457
58+
**Step 2 : Setting up the configuration file**
2559

26-
Setup
27-
-------
60+
The package requires a configuration file where all settings are defined. Create a new file named `.codegreencore.config`` in your root directory. This file will contain all the configurations required to run the package successfully.
2861

29-
After successfully installing the package, the next step is to create a configuration file:
62+
The next section describes how to set up the package based on your requirements.
3063

31-
- Create a new file named `.codegreencore.config`` in your root directory.
32-
- This file will contain all the configurations required to run the package successfully.
33-
- Below is a template for the configuration file:"
64+
65+
Configuring the `codegreen_core` package
66+
-----------------------------------------
67+
68+
The codegreen_core package offers a wide range of functionalities and can be used in many applications.
69+
70+
Below is the template for the basic configuration
3471

3572
.. code-block:: bash
3673
3774
[codegreen]
3875
ENTSOE_token = <token>
39-
enable_energy_caching = false
40-
energy_redis_path = <redis_path>
4176
77+
This configuration allows you to fetch data online and use it.
78+
It is recommended to start with the basic setup and explore the available APIs before making advanced customizations.
4279

43-
Description of the fields in configuration file:
80+
The API of the package is available :doc:`here <api>`
4481

45-
- `ENTSOE_token``: The token required to fetch data from the ENTSO-E portal. Please follow the steps at https://transparency.entsoe.eu to create a free account and obtain an API token.
46-
- `enable_energy_caching``: (boolean) Indicates whether energy data used for optimal time predictions should be cached.
47-
- `energy_redis_path``: The path to the Redis server where energy data will be stored. This field is required if caching is enabled using the above option.
82+
The table below summarizes all available configs :
4883

84+
.. list-table:: Available Configuration Options
85+
:header-rows: 1
86+
:widths: 20 50 10 20
4987

50-
Package Organization
51-
---------------------
88+
* - Name
89+
- Description
90+
- Default
91+
- Possible Values
92+
* - `ENTSOE_token`
93+
- The token required to fetch data from the ENTSO-E portal. Please follow the steps at https://transparency.entsoe.eu to create a free account and obtain an API token.
94+
- None
95+
- String
96+
* - `default_energy_mode`
97+
- To decide the source of energy forecasts to be used for making optimal time predictions
98+
- public_data
99+
- public_data / local_prediction
100+
* - `enable_energy_caching`
101+
- Enables or disables local caching of energy data
102+
- false
103+
- true/false
104+
* - `energy_redis_path`
105+
- Path to Redis instance for caching
106+
- None
107+
- String (Redis URL, redis://localhost:6379 )
108+
* - `enable_offline_energy_generation`
109+
- To enable storing and periodic update of historical energy in csv files
110+
- false
111+
- true/false
112+
* - `offline_data_dir_path`
113+
- Path to the folder where historical energy data will be stored
114+
- None
115+
- String
116+
* - `offline_data_start_date`
117+
- The start date from which historical energy data must be downloaded and stored
118+
- None
119+
- String (`YYYY-mm-dd` format)
52120

53-
.. image:: _static/modules.png
54-
:alt: modules
55-
:width: 400px
56-
:align: center
121+
**Which data is used to predict optimal computation start time ?**
57122

123+
One of the main features of the `codegreen_core` package is the ability to calculate the optimal time for running a computation.
124+
This calculation depends on forecasts of hourly energy generation data from renewable and non-renewable sources or time series forecasts of the carbon intensity of future energy production.
58125

59-
The package is divided into two main sub packages: `data`` and `tools`. (There is also an additional module, `utilities`, which provides helper methods that support other modules.)
126+
While this data is available for some countries, it is typically only provided for short durations (usually 24 hours or less), which limits the accuracy of optimal time predictions.
127+
To address this limitation, we have trained prediction models that generate time series forecasts for longer periods, allowing for more effective optimization.
60128

61-
The `data` sub package contains methods for fetching energy production data. This package relies on external data sources to retrieve this information, which is then processed to make it usable by other components of the package. For more details and a complete API , see the data module documentation.
129+
This setting is controlled by the `default_energy_mode` option. **By default**, the package uses publicly available energy data. To use the trained prediction models (if available for a specific country), set `default_energy_mode` to `local_prediction`.
62130

63-
The `tools` sub package provides a variety of tools, including:
131+
**How to enable caching of recent energy data?**
64132

65-
- Carbon intensity calculator
66-
- Carbon emission calculator
67-
- Optimal time-shifting predictor
68-
- Optimal location-shifting predictor
133+
Certain tools, such as `predict_optimal_time`, rely on recent energy forecasts / predictions. Fetching the same data multiple times can be avoided by intelligently caching it and updating it at regular intervals.
134+
Energy data caching can be enabled by setting `enable_energy_caching` to `true`.
69135

70-
For more information, refer to the `tools` module documentation.
136+
Additionally, this requires a connection to Redis, which is specified using the `energy_redis_path` setting.
137+
When caching is enabled, the package first attempts to connect to Redis before storing or retrieving data.
71138

139+
Once enabled, two types of data values are stored in the cache for each available country:
72140

73-
Example : Calculating optimal time for a computational task
74-
-------------------------------------------------------------
75-
Assuming all the above steps are done, you can now calculate the optimal starting time for a computations.
141+
1. **Hourly time series forecasts** for the upcoming hours.
142+
2. **Actual energy generation data** for the past 72 hours.
76143

77-
.. code-block:: python
78-
79-
from datetime import datetime,timedelta
80-
from codegreen_core.tools.loadshift_time import predict_now
81-
82-
country_code = "DK"
83-
est_runtime_hour = 10
84-
est_runtime_min = 0
85-
now = datetime.now()
86-
hard_finish_date = now + timedelta(days=1)
87-
criteria = "percent_renewable"
88-
per_renewable = 50
89-
90-
time = predict_now(country_code,
91-
est_runtime_hour,
92-
est_runtime_min,
93-
hard_finish_date,
94-
criteria,
95-
per_renewable)
96-
# (1728640800.0, <Message.OPTIMAL_TIME: 'OPTIMAL_TIME'>, 76.9090909090909)
97-
144+
145+
**How to download and use historical energy generation data offline?**
146+
147+
148+
149+
**How to re-train prediction models ?**
150+
TODO
151+
152+
153+
Setting up your own web server
154+
--------------------------------
155+
156+
157+
158+
Deploying the web server using the docker image
159+
-----------------------------------------------

‎docs/index.rst

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,10 @@ Welcome to codegreen_core's documentation!
1111
:caption: Contents:
1212

1313
introduction
14+
methodology
1415
getting_started
15-
data
16-
tools
16+
api
17+
status
1718
references
1819
version_history
1920

‎docs/tools.rst renamed to ‎docs/methodology.rst

Lines changed: 9 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,10 @@
1+
Methodology
2+
============
3+
4+
Here we describe how we calcualte stuff
5+
6+
7+
18
``tools`` Module
29
=================
310

@@ -10,8 +17,7 @@ Each tool is implemented in a separate module and must be imported individually
1017
As a convention, methods that primarily accept DataFrame as an input (along with other parameters) and return a DataFrame are prefixed with `_df`.
1118
1219

13-
.. automodule:: codegreen_core.tools
14-
:members:
20+
1521

1622
Carbon Intensity of Energy
1723
---------------------------
@@ -45,8 +51,7 @@ One challenge with the carbon intensity calculation is that the values can vary
4551

4652
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]
4753

48-
.. automodule:: codegreen_core.tools.carbon_intensity
49-
:members:
54+
5055

5156
Carbon emission of a job
5257
-------------------------
@@ -69,19 +74,3 @@ Carbon emission of a job depends on 2 factors : Energy consumed by the hardware
6974
- Emissions related to the production of the energy : represented by the Carbon Intensity of the energy mix during that period. Already implemented above
7075
- The result is Carbon emission in CO2e
7176

72-
.. automodule:: codegreen_core.tools.carbon_emission
73-
:members:
74-
75-
76-
Optimal time shifting
77-
---------------------
78-
79-
.. automodule:: codegreen_core.tools.loadshift_time
80-
:members:
81-
82-
83-
Optimal Location shifting
84-
-------------------------
85-
86-
.. automodule:: codegreen_core.tools.loadshift_location
87-
:members:

0 commit comments

Comments
 (0)