# Reading Bids Strategy

The [`ReadingBidsStrategy`] is an easy way to pre-program time-varying behavior of a satellite model
without relying on any computation logic. The exact bids that should be submitted to the central
market can be defined, for as many or few days as desired. This strategy will continuously iterate
over the bids, looping back to the start of the file when the end is reached.

Example use cases for this strategy include submitting the same set of profile bids every day, or
defining fixed weekly behavior that will repeat every 7 days.

## Configuration

The [`ReadingBidsStrategy`] has various parameters to configure to perform its function. They
are listed below with an explanation.

These attributes are mandatory: the strategy cannot function without this information. All paths are
interpreted as relative to the location of the configuration file they are specified in. This is the
recommended usage. Alternatively, paths can be given as absolute, although this is discouraged for
the sake of reproducibility across different machines.

- `strategy`
  Must be `reading_bids` to tell `annular` that this file configures a [`ReadingBidsStrategy`].

- `bids_csv_path`
  The bids to be repeated should be listed in this csv file. The expected format is:

| exclusive_group_id | profile_block_id | sense | timestamp | quantity | acceptance_ratio | price |
|--------------------|------------------|-------|-----------|----------|------------------|-------|
| ...                | ...              | ...   | ...       | ...      | ...              | ...   |

  Note that the earliest value in the `timestamp` column must match the first timestamp used by
  the central market and other bidding strategies. The global `start_hour` attribute (or local
  overwrite of it) is ignored.

### Inherited From Global Simulation Settings

- `rolling_horizon_step`
  Defines the number of timesteps for the bidding window. Changing this value to anything other than
  that used for the whole simulation is not recommended, and will likely result in infeasibility
  issues.

Any other globally shared or defined attributes are ignored by this strategy.

## Example

This example assumes the folder structure as suggested in the [basic project] page:

```
energy-system-simulation/
├── ...
├── satellite-configurations/
│   ├── repeating-5h-bids.yml
│   └── ...
└── csv_files/
    ├── repeating-5h-bids.csv
    └── ...
```

The required configuration to add a [`ReadingBidsStrategy`] to the coupled simulation is minimal:

```{literalinclude} ../static/repeating-bids-sample/repeating-5h-bids.yml
:language: yaml
:caption: repeating-5h-bids.yml
```

All behavior is specified in the bids table CSV file. The truncated example below submits a
collection of bids that repeat on a daily basis. It consists of 20 profiles, each for a demand of
75 units of power for 5 consecutive hours. Since all are listed under the same `exclusive_group_id`
(1), and they are all submitted  at ceiling price, exactly one of the profiles will be accepted.

```{table} repeating-5h-bids.csv
| exclusive_group_id | profile_block_id | sense | timestamp        | quantity | acceptance_ratio | price |
|--------------------|------------------|-------|------------------|----------|------------------|-------|
| 1                  | 1                | 1     | 2020-01-01 00:00 | 75       | 1                | 4000  |
| 1                  | 1                | 1     | ...              | 75       | 1                | 4000  |
| 1                  | 1                | 1     | 2020-01-01 04:00 | 75       | 1                | 4000  |
| 1                  | 2                | 1     | 2020-01-01 01:00 | 75       | 1                | 4000  |
| 1                  | 2                | 1     | ...              | 75       | 1                | 4000  |
| 1                  | 2                | 1     | 2020-01-01 05:00 | 75       | 1                | 4000  |
| 1                  | ...              | 1     | ...              | 75       | 1                | 4000  |
| 1                  | 20               | 1     | 2020-01-01 19:00 | 75       | 1                | 4000  |
| 1                  | 20               | 1     | ...              | 75       | 1                | 4000  |
| 1                  | 20               | 1     | 2020-01-01 23:00 | 75       | 1                | 4000  |
```

You can also download the [full CSV file][sample-table], or a [zip file][sample-zip] containing both
the CSV and configuration YAML files in their respective folders.


<!-- References -->
[basic project]:            project:../basic-project.md
[sample-zip]:               ../static/repeating-bids-sample/repeating-5h-bids.zip
[sample-table]:             ../static/repeating-bids-sample/repeating-5h-bids.csv
[`ReadingBidsStrategy`]:    #annular.satellite_model.ReadingBidsStrategy