This repository contains template code from which new vantage6 algorithms can be created. By answering a number of questions, a personalized template will be created that allows the algorithm developer to focus on the algorithm rather than on the infrastructure around it.
The template generator used in the background is copier.
You can create your own vantage6 algorithm template by running
v6 algorithm create
and this will start a questionnaire to help you personalize your algorithm. Be sure that your vantage6 version is at least 4.1.0 - the command is only available from that version onwards.
Alternatively, you can also run it outside of the vantage6 CLI:
# install required dependencies in your python environment
pip install copier pyyaml
# Create a new algorithm template
copier copy https://github.com/vantage6/v6-algorithm-template /path/to/my/new/algorithm
After creating the template, follow the checklist in the README to complete your algorithm!
You can also do this when you have already implemented your algorithm!
This algorithm template generator may be updated for several reasons: it is extended with new questions to personalize your template further, it contains a bug, the vantage6 algorithm structure is updated, etc. In such cases, you should update your algorithm. You can do so with
v6 algorithm update
which will take the latest version of this repository and use it to update the algorithm code.
You can also use the copier CLI:
# install required dependencies in your python environment
pip install copier pyyaml
# Update an existing algorithm
copier copy https://github.com/vantage6/v6-algorithm-template /path/to/my/new/algorithm
To release a new version of the template generator, a new tag has to be added
with the semantic versioning format (e.g. 1.2.3
). Copier does not use the
latest on a certain main branch, but requires these tags to find the most recent
version of the template. So to release a new version, do:
git tag x.y.z
git push origin x.y.z
Note that we therefore do not follow the vantage6 way of defining tags with a
version/
prefix - this does not conform to the copier
standard.
When developing a new version of the template generator, you can test it by
copier copy --trust --vcs-ref=HEAD . /path/to/my/new/algorithm
The --vcs-ref=HEAD
flag will ensure that local changes are taken into account
when generating the template. This is useful when developing new features because then
it is not necessary to commit changes to test them.
Also note the --defaults
option to fill out the same answers to the questions as in
the previous iteration, and the -w
to overwrite files from last time without asking
confirmation.
copier copy --vcs-ref=HEAD -w --defaults --trust . /path/to/my/new/algorithm