Collection of scripts and additional information to help developers.
To clone/install/update all ubermag subpackages we use invoke (can be
installed via pip or conda, see below). Tasks are defined in tasks.py. To
get a list of all possible options run:
invoke --listTo get more detailed help on one specific command, run:
invoke --help <command>We assume/create a directory structure where all subpackages are contained
within one base directory, here called ubermag-devtools/repos:
ubermag-devtools
+-- .git
+-- ...
+-- repometadata
| +-- ...
+-- repos
| +-- discretisedfield
| | +-- .git
| | +-- ...
| +-- micromagneticdata
| | +-- .git
| | +-- ...
| +-- ...
+-- tasks.py
To get started clone the devtools repository via ssh:
git clone git@github.com:ubermag/devtools.git ubermag-devtoolsor https if you don't have an ssh key:
git clone https://github.com/ubermag/devtools.git ubermag-devtoolsand change into that directory (we clone the devtools repository to a custom
location ubermag-devtools which is more explicit). Your directory layout
should then be similar to (not all content of the devtools repository is shown
here):
ubermag-devtools
+-- .git
+-- repometadata
| +-- ...
+-- tasks.py
If required install conda. Suggestion: use miniforge.
Create a new conda environment, here called ubermagdev312, and install the most
basic packages (python, pip, oommf, colorama and invoke) from conda-forge channel using
conda (everything else later on will be installed via pip).
We use conda for this step because it simplifies the installation of OOMMF.
conda env create -f environment.yaml
conda activate ubermagdev312We use Python version 3.12 to benefit from the performance improvements in
recent Python versions. Note that Python 3.8 is the oldest version currently
supported by ubermag so no features of newer Python versions can be used.
invoke clone -p ssh install-p <ssh|https>(--protocol ...) clone repositories usingsshorhttps
This will create a new directory repos and clone all repositories into that
directory using the specified protocol. Then all packages are installed in
development mode. Your directory tree should now look like outline in the
beginning.
invoke clone-extras -p sshClones the following additional repositories:
helpmumax3ctutorialsubermag.github.io(the website repository)workshop
python -c "import ubermag; ubermag.test()"Pull changes in all code repos:
invoke per-repo "git pull"See invoke --help per-repo for available options.
invoke per-repo "pre-commit install"invoke uninstallrepometadata contains templates and additional helper scripts to update
metadata common to all repositories. The metadata can be updated using the
invoke task update-repometadata
The update will only work for the directory structure explained above. Follow the instructions in the first section of this README.
The repometadata can locally be updated using the invoke task
update-repometadata. The task can update one or multiple repositories at the
same time. Furthermore, it can work on different branches, both existing and
new ones. To get a list of available options and additional help, run
$ invoke --help update-repometadataAvailable options are:
r <REPO>/--repo <REPO>name of the repository; can be passed multiple times to update multiple repositories simultaneously; if omitted all repositories are updated-f <FILE>/--file <FILE>name of the file to update; can be passed multiple times ore omitted like-r-b <BRANCH>/--branch <BRANCH>name of the branch to use; can be an existing or a new one-c/--create-branchrequired if-bspecifies a new branch that must be created (uses thegitoption-Bso it will overwrite existing branches)-o <MESSAGE>/--commit-message <MESSAGE>custom commit message; if not specified the default is"Update repository metadata"--[no-]pushpush or do not push the changes; default is true, i.e.pushchanges
Examples:
-
Update all files in all repositories on a new (
-c) branchmetadata-updateand push the changes:$ invoke update-repometadata -b metadata-update -c
-
Update all files in
ubermagutilanddiscretisedfieldon themasterbranch but do not push changes:$ invoke update-repometadata -r ubermagutil -r discretisedfield -b master --no-push
-
Update
README.mdin all repositories using a new (-c) branchrepo-metadatawith a special commit message and push the changes:$ invoke update-repometadata -f README.md -b repo-metadata -c --commit-message "Update README"