Forecasting Electricity Demand with TDgpt

As a core tool in modern energy management, electricity demand forecasting delivers value throughout the entire lifecycle of the power system. At the resource planning level, accurately predicting electricity usage trends enables the optimization of power generation facility layout and the timing of grid upgrades. This helps avoid idle resources caused by premature investments or supply gaps resulting from delayed construction, and in typical scenarios, it can improve infrastructure investment efficiency by 15%–20%.

For power operators, load forecasting supports dynamic optimization from fuel procurement to unit dispatching. In thermal power generation, this has led to over a 2% improvement in coal-to-power efficiency. Additionally, by smoothing peaks and valleys in electricity demand, it reduces the need for grid reserve capacity and significantly cuts system operating costs.

From the perspective of energy security, forecasting technologies establish a buffer mechanism between power supply and demand. For every 1% reduction in short-term forecasting error, the corresponding reduction in emergency peak-shaving costs can reach 3%–5% of a regional grid’s average daily operating expenses—an especially critical factor when dealing with extreme weather or unexpected events.

Medium- and long-term forecasting provides a decision-making foundation for inter-regional power sharing and energy storage deployment, effectively mitigating structural power shortage risks. In market environments, forecasting capabilities translate directly into economic gains. Power generation companies use 96-interval day-ahead load forecasts to optimize bidding strategies, potentially securing an additional 10%–18% in price arbitrage opportunities in electricity spot markets. Meanwhile, commercial and industrial users analyze load patterns to tailor their energy usage plans, achieving annual electricity cost reductions of 5%–10%.

This article provides a guide for quickly setting up a TDgpt test environment using Docker Compose. Based on this environment and real-world data, it demonstrates the full process of day-ahead electricity demand forecasting. The goal is to help users quickly get hands-on with TDgpt and rapidly gain AI-powered capabilities in time-series data forecasting and anomaly detection.

What Is TDgpt?

TDgpt is an intelligent agent built into TDengine for time-series data analysis. Leveraging TDengine’s time-series query capabilities, it provides advanced analysis functions—such as time-series forecasting and anomaly detection—through SQL, with the ability to dynamically extend and switch analysis tasks at runtime. By integrating prebuilt time-series foundation models, large language models, machine learning, and traditional algorithms, TDgpt enables engineers to deploy time-series forecasting and anomaly detection models within 10 minutes. This reduces the development and maintenance costs of time-series analysis models by at least 80%.

Learn more about TDgpt.

Prepare the Demo Dataset

We use the publicly available UTSD dataset’s electricity demand data as the source for our forecasting algorithm, aiming to predict electricity demand for several hours ahead based on historical data. The dataset has a sampling frequency of 30 minutes, but it does not include units or timestamps. For demonstration purposes, we generated timestamps in reverse from 2025-01-01 00:00:00 at 30-minute intervals and stored the data in the corresponding TDengine table.

The dataset contains five files, and for this demonstration, we use the subset with the highest index number. This data file is located in the demo_data directory of the TDgpt-demo repository. The following procedure shows how to import the data into TDengine and complete the demonstration. The dataset is described as follows:

Preparing the Demo Environment

Prerequisites

The demo is run in Docker and does not require a specific operating system. However, the following are required to use Docker Compose:

1. Git
2. Docker Engine: v20.10+
3. Docker Compose: v2.20+

The demo contains three Docker containers (TDengine, TDgpt, and Grafana) and shell scripts that generate forecasting or anomaly detection results.

Procedure

1. Clone the demo repository and make the script file executable:

   git clone https://github.com/taosdata/TDgpt-demo
   cd TDgpt-demo
   chmod 775 analyse.sh

2. Navigate to the directory containing the docker-compose.yml file and run the following command to start the integrated demo environment with TDengine, TDgpt, and Grafana:

   docker-compose up -d

3. Wait 10 seconds and then register the anode to TDengine:

   docker exec -it tdengine taos -s "create anode 'tdgpt:6090'"

4. Initialize the data for the test environment:

   docker cp analyse.sh tdengine:/var/lib/taos
   docker cp demo_data tdengine:/var/lib/taos
   docker exec -it tdengine taos -s "source /var/lib/taos/demo_data/init_electricity_demand.sql"

Your demo environment has now been created. To remove the environment if it is no longer needed, run the following command:

docker-compose down

Running the Demo

1. Open your browser and go to http://localhost:3000, then log in to Grafana using the default username and password: admin / admin.

2. After logging in successfully, navigate to “Home → Dashboards”, then import the electricity_demand.json file to load the preconfigured dashboard.

   

3. After importing, select the “electricity_demand” dashboard. This panel is preconfigured to display the actual values along with forecast results from TDtsfm_1 and HoltWinters. At this point, only the data curve for the actual values is visible.

4. Run analyse.sh to begin forecasting. First try forecasting with TDtsfm:

   docker exec -it tdengine /var/lib/taos/analyse.sh --type forecast --db tdgpt_demo --table electricity_demand --stable single_val --algorithm tdtsfm_1 --params "fc_rows=48,wncheck=0" --start "2024-01-01" --window 30d --step 1d

   The shell script mentioned above starts from the specified time point (2024-01-01), using data from the previous month as input to predict electricity demand for the next day at 30-minute intervals (a total of 48 data points) using the TDtsfm_1 algorithm. This process continues until it reaches the last record in the electricity_demand table, with all prediction results written into the electricity_demand_tdtsfm_1_result table.

   Before running another forecast, the script will create or remove the results table. During execution, the console will continuously display output in daily increments, showing results like the following:

   Processing window: 2024-01-12 00:00:00 → 2024-02-11 00:00:00
   Welcome to the TDengine Command Line Interface, Client Version:3.3.6.0
   Copyright (c) 2023 by TDengine, all rights reserved.
   
   taos> INSERT INTO tdgpt_demo.electricity_demand_tdtsfm_1_result SELECT _frowts, forecast(val, 'algorithm=tdtsfm_1,fc_rows=48,wncheck=0')
                  FROM tdgpt_demo.electricity_demand
                  WHERE ts >= '2024-01-12 00:00:00' AND ts < '2024-02-11 00:00:00'
   Insert OK, 48 row(s) affected (0.238208s)

5. In the Grafana dashboard, set the refresh interval to 5 seconds to dynamically display the yellow curve representing the prediction results. This allows for a clear visual comparison with the actual values. For better clarity, hold the Command key (on Mac) or the Windows key (on Windows) and click on the “Real” and “TDtsfm_1” legends in the bottom left corner to display only these two curves.

   

6. Now forecast using Holt-Winters:

   docker exec -it tdengine /var/lib/taos/analyse.sh --type forecast --db tdgpt_demo --table electricity_demand --stable single_val --algorithm holtwinters --params "rows=48,period=48,wncheck=0,trend=add,seasonal=add" --start "2024-01-01" --window 30d --step 1d

From the prediction results, we can see that TDtsfm_1 significantly outperforms the traditional statistical method Holt-Winters in terms of accuracy. Beyond prediction precision, a major drawback of the Holt-Winters algorithm is its heavy reliance on meticulous parameter tuning. Without careful adjustment, it is prone to frequent anomalies in the predicted values, such as the spikes and dips shown in the figure below.

By using the mouse to select a specific time range, we can zoom in and examine the fine-grained comparison between the predicted results and the actual values over that period.

You can also experiment with other algorithms or models to find the one that best fits your specific scenario.

Conclusion

In this article, we demonstrated the process of using TDgpt for electricity demand forecasting. As shown, building time-series data analysis with TDgpt allows for seamless integration with applications through SQL, and results can be visualized using Grafana. This greatly reduces the cost of developing and applying time-series forecasting and anomaly detection solutions.

In terms of forecasting performance, the Transformer-based pre-trained model TDtsfm_1 demonstrates significantly better results than the Holt-Winters model on the dataset used. In real-world scenarios, users should select and fine-tune models and algorithms based on the characteristics of their data. Trying out different algorithms or models is also encouraged to find the best fit for specific use cases.