Getting Started

Requirements

• Python 3.8+ (see .python-version with pyenv)

• Docker and docker-compose if you want to run the local development stack with a database

Check if you have the correct python version in your shell:

$ python -V
Python 3.9.6

If you require assistance setting up a local python environment, see the pyenv homepage and documentation.

Quickstart

Install the PyPI module

$ pip install opennem

You can now import the module from a Python script or REPL.

$ ipython
>>> import opennem

Usage

The following method calls makes a live API request to the OpenNEM servers and returns a list of networks.

>>> import opennem
>>> opennem.api.networks()
[NetworkSchema(code='WEM', country='au', label='WEM', regions=[NetworkRegionSchema(code='WEM', timezone=None)], timezone='Australia/Perth', interval_size=30),
 NetworkSchema(code='NEM', country='au', label='NEM', regions=[NetworkRegionSchema(code='NSW1', timezone=None), NetworkRegionSchema(code='QLD1', timezone=None), NetworkRegionSchema(code='VIC1', timezone=None), NetworkRegionSchema(code='TAS1', timezone=None), NetworkRegionSchema(code='SA1', timezone=None)], timezone='Australia/Sydney', interval_size=5)]

The call to opennem.api.fueltechs makes a live HTTP request to the OpenNEM API and returns a list of supported fueltechs in well-defined schemas.

>>> opennem.api.fueltechs()
[FueltechSchema(code='battery_charging', label='Battery (Charging)', renewable=True),
 FueltechSchema(code='battery_discharging', label='Battery (Discharging)', renewable=True),
 FueltechSchema(code='coal_black', label='Coal (Black)', renewable=False),
 FueltechSchema(code='coal_brown', label='Coal (Brown)', renewable=False),
 FueltechSchema(code='distillate', label='Distillate', renewable=False),
 FueltechSchema(code='gas_ccgt', label='Gas (CCGT)', renewable=False),
 FueltechSchema(code='gas_ocgt', label='Gas (OCGT)', renewable=False),
 FueltechSchema(code='gas_recip', label='Gas (Reciprocating)', renewable=False),
 FueltechSchema(code='gas_steam', label='Gas (Steam)', renewable=False),
 FueltechSchema(code='hydro', label='Hyrdo', renewable=True),
 FueltechSchema(code='pumps', label='Pumps', renewable=True),
 FueltechSchema(code='solar_utility', label='Solar (Utility)', renewable=True),
 FueltechSchema(code='solar_thermal', label='Solar (Thermal)', renewable=True),
 FueltechSchema(code='solar_rooftop', label='Solar (Rooftop)', renewable=True),
 FueltechSchema(code='wind', label='Wind', renewable=True),
 FueltechSchema(code='aggregator_vpp', label='Aggregator (VPP)', renewable=True),
 FueltechSchema(code='aggregator_dr', label='Aggregator (Demand / Response)', renewable=True),
 FueltechSchema(code='nuclear', label='Nuclear', renewable=True),
 FueltechSchema(code='imports', label='Network Import', renewable=False),
 FueltechSchema(code='exports', label='Network Export', renewable=False),
 FueltechSchema(code='bioenergy_biogas', label='Biogas', renewable=False),
 FueltechSchema(code='bioenergy_biomass', label='Biomass', renewable=False),
 FueltechSchema(code='gas_wcmg', label='Gas (Coal Mine Waste)', renewable=False)]

Example Project

Guided steps for starting a client implemention of the OpenNEM library that will access the API and return data.

First, create a directory for your project and enter that direcoty:

$ mkdir ~/Work/energy_data
$ cd ~/Work/energy_data

Next we need to create a virtual environment for this project, where all the python requirements will be installed. This command creates a virtual environment in the project directory in a folder called .venv

$ python -m venv .venv

Before continuing, we’d like to setup this project as a git repository so that we can track changes and revisions while we work to develop on it.

The .venv directory needs to be added to .gitignore so that it is not checked in as part of the repository. The virtual environment is local to the developers machine.

$ git init
Initialized empty Git repository in /Users/n/Work/energy_data/.git/

When you check the git status, you’ll see that it picks up the virtual environment .venv folder:

$ git status
On branch main

No commits yet

Untracked files:
	.venv/

nothing added to commit but untracked files present

We do not want to commit the virtual environment to the repository so we ignore it by adding the path to a .gitignore file and commiting that file to the repository

$ echo ".venv" >> .gitignore
$ git add .gitignore
$ git commit -m "Added the venv to gitignore"
[main 469dddd] Added the venv to gitignore
 1 file changed, 1 insertion(+)
 create mode 100644 test.txt

We now have a setup virtual environment with a git repository. Next we will activate the virtual environment. You can verify that the shell has activated the virtual environment by looking at the path to the python binary.

$ source .venv/bin/activate
$ which python
/Users/n/Work/energy_data/.venv/bin/python

We can now install the opennem client library

$ pip install opennem

This install might take a moment. Once done, we can use the client library in a REPL like iPython like so:

$ ipython
Python 3.9.6 (default, Jun 28 2021, 19:24:41)
Type 'copyright', 'credits' or 'license' for more information
IPython 7.26.0 -- An enhanced Interactive Python. Type '?' for help.

In [1]: import opennem

We can use a Jupyter notebook by adding it as a dependancy to the project and starging it:

$ pip install jupyter
$ jupyter notebook

There is a local .jupyter config that will setup a profile to run a notebook and includes an example notebook in notebooks/