Algorithms for Hilbert modular groups
Project description
Hilbert Modular Groups
This repository contains a python package hilbert_modgroup
that implements algorithms
for Hilbert modular groups, in particular a reduction algorithm. The implementation is written in Python
and is dependent on SageMath.
Requirements
- SageMath v9.6+ (https://www.sagemath.org/) (Tested on v9.6, v9.7, v10.0 and v10.2)
Installation
Using sage pip
This package needs to be installed in the virtual environment provided by SageMath, and it is therefore necessary to run the following command
$ sage -pip install --no-build-isolation hilbert-modular-group
Note: The --no-build-isolation
is 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 source
If the SageMath executable sage
is in the current path you can install from source using the Makefile
$ git clone https://github.com/fredstro/hilbertmodgroup.git
$ cd hilbertmodgrup
$ make install
Docker
If 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-sage
or make docker-examples
Usage
The 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 for EXAMPLES
) as well as
the /examples
directory which contains Jupyter notebook with more extensive
examples corresponding to the paper
"Reduction Algorithms for Hilbert Modular Groups" by F. Stromberg. (Reference to appear)
Examples
The directory /examples
contains 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 examples
make docker-examples
which will start up a Jupyter notebook server from sagemath either locally or in a docker container.
Community Guidelines
How to Contribute?
- Open an issue on GitHub and create a pull / merge request against the
develop
branch.
How to report an issue or a problem?
- First check if the issue is resolved in the
develop
branch. If not, open an issue on GitHub.
How to seek help and support?
- Contact the maintainer, Fredrik Stromberg, at: fredrik314@gmail.com (alternatively at fredrik.stromberg@nottingham.ac.uk)
Development and testing
The make file Makefile
contains 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/examples
directory.tox
-- runsage -tox
with all environments:doctest
,coverage
,pycodestyle
,relint
,codespell
Note: 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/examples
directory and exposing the notebook at http://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 container
The following command-line parameters are available
NBPORT
-- set the port of the notebook forexamples
anddocker-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 usage
Run tox coverage on the branch main
from gitHub:
make docker-tox REMOTE_SRC=1 GIT_BRANCH=main TOX_ARGS=coverage
Run doctests on the local source with local version of sage:
make tox TOX_ARGS=doctest
Run relint on the local source with docker version of sage:
make docker-tox REMOTE_SRC=0 TOX_ARGS=relint
Development
GitHub Workflow
- There are two long-lived branches
main
anddevelop
. - The
develop
branch is used for development and can contain new / experimental features. - Pull-requests should be based on
develop
. - Releases should be based on
main
. - The
main
branch should always be as stable and functional as possible. In particular, merges should always happen fromdevelop
intomain
. - Git-Flow is enabled (and encouraged) with feature branches based on
develop
and hotfixes based onmain
.
GitHub Actions
Each 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
-- spellchecker
To make sure that your commit passes all tests you should make tox
or make docker-tox REMOTE_SRC=0
on the command line.
Versions
Versioning of this project is managed by setuptools_scm.
To bump the version create a git tag x.y.z
and the file
src/hilbert_modgroup/version.py
will then be automatically updated to contain
version = '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.
PyPi
To upload new versions to PyPi:
make sdist
-- creates a source distributiondist/hilbert_modular_group-x.y.z
twine check dist/hilbert_modular_group-x.y.z
twine upload --repository pypi dist/hilbert_modular_group-z.y.z
References:
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Hashes for hilbert_modular_group-0.1.2.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 89513da23ba4ce1ee5d332e10f4b3b219ab82922388f01551f3f6314b912efa2 |
|
MD5 | 71b0940ce1075020758159e871152ce5 |
|
BLAKE2b-256 | 049f78edcf96ca18c723c3028304613df655c69a90e9755f7bd255410893af0d |