> ## Documentation Index
> Fetch the complete documentation index at: https://docs.engrate.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> Use engratepy to calculate and optimise cost of energy in Python.

`engratepy` is Engrate's Python SDK for Cost of Energy.

```bash theme={null}
pip install engratepy
```

Use it to:

* calculate tariff cost from your own time-series data
* discover which input datasets a tariff needs
* embed tariff cost into optimisation models ([HiGHS](https://highs.dev) and [Gurobi](https://www.gurobi.com))

## Authenticate

Create a client with your [API key](/guides/authentication):

```python theme={null}
from engratepy import Engrate

engrate = Engrate(api_key="YOUR_API_KEY")
```

## Discover Required Input Datasets

Before calculating or optimising, you can ask the SDK which datasets the tariff requires for the calculation period:

```python theme={null}
datasets = await engrate.get_input_datasets(
    tariff_id=tariff_id,
    start_time=...,
    end_time=...,
)
```

## Calculate Cost

Run a cost calculation over a period:

```python theme={null}
costs_per_tariff_component = await engrate.calculate_cost(
    tariff_id=tariff_id,
    start_time=...,
    end_time=...,
    data={dataset: {timestamp: value, ...}},  # dataset from get_input_datasets
)
```

## Use in Optimisation Models

`engratepy` can even add tariff costs directly to solver models:

<CodeGroup>
  ```python HiGHS theme={null}
  import highspy

  model = highspy.Highs()

  costs_per_tariff_component = await engrate.add_to_highs_model(
      tariff_id=tariff_id,
      start_time=...,
      end_time=...,
      data={dataset: {timestamp: value, ...}},     # fixed inputs, e.g. spot prices
      variables={dataset: {timestamp: variable, ...}},  # your decision variables
      model=model,
  )
  ```

  ```python Gurobi theme={null}
  import gurobipy

  model = gurobipy.Model()

  costs_per_tariff_component = await engrate.add_to_gurobi_model(
      tariff_id=tariff_id,
      start_time=...,
      end_time=...,
      data={dataset: {timestamp: value, ...}},     # fixed inputs, e.g. spot prices
      variables={dataset: {timestamp: variable, ...}},  # your decision variables
      model=model,
  )
  ```
</CodeGroup>

The model is extended in place, and cost is returned per component, either as a variable into the model, with constraints tying it to your decision variables, or as plain numbers where it is fixed.

Need support for another solver? We would love to hear from you - contact [support@engrate.io](mailto:support@engrate.io) and we can discuss your use case.

## Cookbook

For full working examples, take a look at our [cookbook](https://github.com/engrate/engrate-cookbook).

## License

`engratepy` is available under an evaluation license.

You are welcome to use it for internal evaluation, testing, learning, and prototyping in non-production environments.

Production or commercial use requires a separate signed commercial license with Engrate. To discuss commercial licensing, contact [support@engrate.io](mailto:support@engrate.io).

## Related Docs

* [Cost of Energy API Overview](/api-reference/cost-of-energy/overview)
* [Calculation Pipeline](/api-reference/cost-of-energy/calculation-pipeline)
* [Tariff](/api-reference/cost-of-energy/models/tariff)
* [Tariff Component](/api-reference/cost-of-energy/models/tariff-component)