Annular-Tulipa integration

Integration with Tulipa: proof of concept

Closes #103 (closed)

Features

• Adds submodule central_market market, in which
  • base.py is the existing Python implementation
  • tulipa/ has the equivalent for the Tulipa market model
• coupling.py: track iteration id for debugging and storing results from the TulipaEnergyModel of each iteration
• full_run_market_model run_market_model: single wrapper function setting up the model, solving and returning solution. For consistency, for both implementations of the market model they have the same signature but each use only a (different) subset of the arguments. They do not have the same signature; arguments are created in coupling.py depending on the market model. In the base market module, the old run_market_model has been renamed to solve_market_model.
• CLI option to install TulipaEnergyModel and dependencies, given Julia is installed and accessible with julia from a terminal. User can manage their own installation too. For developers, the julia environment should be installed in the virtual environment, and we (believe) the tests take care of this automatically, but this should be checked again (does it do it on CI?)

Other

• The user is responsible for validating the Tulipa data used by annular. Annular does a basic check to ensure the model can run mechanically but makes not guarantees about correctness of the solution.

Documentation

Basic documentation for installation, usage, and user-facing limitations is added.

Testing

The added code has a 3-layered testing strategy

1. unit tests for the interface with Tulipa: make sure bid information is correctly encoded in tables used by Tulipa. I think this is important documentation., and I may write some more developer documentation for this.
2. market model "unit" tests: check the market model works correctly for a given configuration. Similar tests as for the annular central market, but limited to the TestMarketClearingSupplyBids class.
3. Integration tests with muscle3 in test_coupling_module.py. Also builds on existing tests, but they only test that the tool runs, not for correctness

For layers 2&3, the test suite uses parmaterization across the market implementations (base and tulipa). The test IDs are generated as "market.X" where x in [base, tulipa]. This allows for excluding slow tests with the -k "not market.tulipa" flag.

CI

To have reasonably fast tests on CI, we use said flag. In .gitlab-ci.yml, we added an additional workflow step to test tulipa-related code specifically whenever these files are changed.

To do from https://github.com/abelsiqueira/annular/pull/1

• update tulipa builder version
• sync -k tulipa and -k "not demolipa" in tests and think about how to measure coverage in this setup

Design document: https://github.com/ESI-FAR/wiki/blob/main/generalization/demoses-tulipa/integration-design.md

Related

• Known limitations of this PR/integration: #152
• Other observations we made: #146

Checklist

• Formatting matches prescribed style
• Tests pass
• Code coverage does not decrease
• New tests have been added for new code
• Relevant documentation has been updated or added
• User-facing changes have been listed in [CHANGELOG.md]