Package: hilbert-modular-group
Hilbert Modular GroupsThis repository contains a python packagehilbert_modgroupthat implements algorithms
for Hilbert modular groups, in particular a reduction algorithm. The implementation is written in Python
and is dependent on SageMath.RequirementsSageMath v9.6+ (https://www.sagemath.org/)
(Tested on v9.6, v9.7 and v10.0)InstallationUsing sage pipThis package needs to be installed in the virtual environment provided by SageMath, and it is therefore necessary
to run the following command$sage-pipinstall--no-build-isolationhilbert-modular-groupNote: The--no-build-isolationis necessary as the compiler needs access
to certain library files from the sage installation and SageMath itself is
too large to be required as a build dependency.
As an alternative to this flag you can also specify the environment variable
SAGE_LIB explicitly.From git sourceIf the SageMath executablesageis in the current path you can install from source using the Makefile$gitclonehttps://github.com/fredstro/hilbertmodgroup.git$cdhilbertmodgrup$makeinstallDockerIf you do not have SageMath installed, but you have docker you can use install this package
in a docker container built and executed using e.g.make docker-sageormake docker-examplesUsageThe package can be imported and used as any other package.
For example, to find the reduction of the point given by [1+i,1+i] in H^2
with respect to the Hilbert modular group of Q joint by square-root of 5 write:sage: from hilbert_modgroup.all import *
sage: H1=HilbertModularGroup(5)
sage: P1=HilbertPullback(H1)
sage: z = UpperHalfPlaneProductElement([1+I,1+I])
sage: P1.reduce(z)
[1.00000000000000*I, 1.00000000000000*I]
sage: z = UpperHalfPlaneProductElement([0.25+I/2,1+I])
sage: P1.reduce(z) # abs tol 1e-10
[0.694427190999916 + 0.611145618000168*I, -0.309016994374947 + 1.30901699437495*I]
sage: P1.reduce(z, return_map=True)[1]
[-1/2*a + 1/2  1/2*a + 1/2]
[-1/2*a + 1/2            0]For more examples see the embedded doctests (search forEXAMPLES) as well as
the/examplesdirectory which contains Jupyter notebook with more extensive
examples corresponding to the paper
"Reduction Algorithms for Hilbert Modular Groups" by F. Stromberg. (Reference to appear)ExamplesThe directory/examplescontains Jupyter notebooks with example code to illustrate the interface and functionality of this package.
You can either open them manually from SageMath or run one of the following commands:make examplesmake docker-exampleswhich will start up a Jupyter notebook server from sagemath either locally or in a docker container.Community GuidelinesHow to Contribute?Open an issue on GitHub and create a pull / merge request against thedevelopbranch.How to report an issue or a problem?First check if the issue is resolved in thedevelopbranch. If not, open an issue on GitHub.How to seek help and support?Contact the maintainer, Fredrik Stromberg, at:fredrik314@gmail.com(alternatively atfredrik.stromberg@nottingham.ac.uk)Development and testingThe make fileMakefilecontains a number of useful commands that you can run using$make<command>The following commands are run in your local SagMath environment:build-- builds the package in place (sometimes useful for development).sdist-- create a source distribution in /sdist (can be installed usingsage -pip install sdist/<dist name>)install-- build and install the package in the currently active sage environmentclean-- remove all build and temporary filestest-- run sage's doctests (same assage -t src/*)examples-- run a Jupyter notebook with the SageMath kernel initialised at the/examplesdirectory.tox-- runsage -toxwith all environments:doctest,coverage,pycodestyle,relint,codespellNote: If your local SageMath installation does not contain tox this will runsage -pip install tox.The following commands are run in an isolated docker container
and requires docker to be installed and running:docker-- build a docker container with the taghilbertmodgroup-{GIT_BRANCH}docker-rebuild-- rebuild the docker container without cachedocker-test-- run SageMath's doctests in the docker containerdocker-examples-- run a Jupyter notebook with the SageMath kernel initialised at the/examplesdirectory
and exposing the notebook athttp://127.0.0.1:8888. The port used can be modified bydocker-tox-- run tox with all environments:doctest,coverage,pycodestyle,relint,codespell.docker-shell-- run a shell in a docker containerdocker-sage-- run a sage interactive shell in a docker containerThe following command-line parameters are availableNBPORT-- set the port of the notebook forexamplesanddocker-examples(default is 8888)TOX_ARGS-- can be used to select one or more of the tox environments (default is all)REMOTE_SRC-- set to 0 if you want to use the local source instead of pulling from gitHub (default 1)GIT_BRANCH-- the branch to pull from gitHub (used if REMOTE_SRC=1)Example usageRun tox coverage on the branchmainfrom gitHub:make docker-tox REMOTE_SRC=1 GIT_BRANCH=main TOX_ARGS=coverageRun doctests on the local source with local version of sage:make tox TOX_ARGS=doctestRun relint on the local source with docker version of sage:make docker-tox REMOTE_SRC=0 TOX_ARGS=relintDevelopmentGitHub WorkflowThere are two long-lived branchesmainanddevelop.Thedevelopbranch is used for development and can contain new / experimental features.Pull-requests should be based ondevelop.Releases should be based onmain.Themainbranch should always be as stable and functional as possible. In particular, merges should always happen fromdevelopintomain.Git-Flow is enabled (and encouraged) with feature branches based ondevelopand hotfixes based onmain.GitHub ActionsEach commit is tested and checked using gitHub actions with tox running:doctest-- run all doctestscoverage-- ensure that all functions and classes are documentedpycodestyle-minimal-- ensure PEP8 style guide is followed (except we allow max line length 99)relint-- relint against some patterns taken from the SageMath source (config file .relint.yaml)codespell-- spellcheckerTo make sure that your commit passes all tests you shouldmake toxormake docker-tox REMOTE_SRC=0on the command line.VersionsVersioning of this project is managed by setuptools_scm.
To bump the version create a git tagx.y.zand the filesrc/hilbert_modgroup/version.pywill then be automatically updated to containversion = 'x.y.z.???'
version_tuple = (x, y, z, '???')where ??? depends on the state of the current directory.
If you are creating a new version to release the source directory should be clean.PyPiTo upload new versions to PyPi:make sdist-- creates a source distributiondist/hilbert_modular_group-x.y.ztwine check dist/hilbert_modular_group-x.y.ztwine upload --repository pypi dist/hilbert_modular_group-z.y.zReferences: