# 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
```console
$ 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
```console
$ 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
```console
$ make <command>
```
The following commands are run in your local SagMath environment:
1. `build` -- builds the package in place (sometimes useful for development).
2. `sdist` -- create a source distribution in /sdist (can be installed using `sage -pip install sdist/<dist name>`)
3. `install` -- build and install the package in the currently active sage environment
4. `clean` -- remove all build and temporary files
5. `test` -- run sage's doctests (same as `sage -t src/*`)
6. `examples` -- run a Jupyter notebook with the SageMath kernel initialised at the `/examples` directory.
7. `tox` -- run `sage -tox` with all environments: `doctest`, `coverage`, `pycodestyle`, `relint`, `codespell`
Note: If your local SageMath installation does not contain tox this will run `sage -pip install tox`.
The following commands are run in an isolated docker container
and requires docker to be installed and running:
1. `docker` -- build a docker container with the tag `hilbertmodgroup-{GIT_BRANCH}`
2. `docker-rebuild` -- rebuild the docker container without cache
3. `docker-test` -- run SageMath's doctests in the docker container
4. `docker-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 by
5. `docker-tox` -- run tox with all environments: `doctest`, `coverage`, `pycodestyle`, `relint`, `codespell`.
6. `docker-shell` -- run a shell in a docker container
7. `docker-sage` -- run a sage interactive shell in a docker container
The following command-line parameters are available
- `NBPORT` -- set the port of the notebook for `examples` and `docker-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` and `develop`.
- 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 from `develop` into `main`.
- Git-Flow is enabled (and encouraged) with feature branches based on `develop` and hotfixes based on `main`.
### GitHub Actions
Each commit is tested and checked using gitHub actions with tox running:
- `doctest` -- run all doctests
- `coverage` -- ensure that all functions and classes are documented
- `pycodestyle-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:
1. `make sdist` -- creates a source distribution `dist/hilbert_modular_group-x.y.z`
2. `twine check dist/hilbert_modular_group-x.y.z`
3. `twine upload --repository pypi dist/hilbert_modular_group-z.y.z`
## References:
- [](https://doi.org/10.21105/joss.03996)
Raw data
{
"_id": null,
"home_page": "https://github.com/fredstro/hilbertmodgroup",
"name": "hilbert-modular-group",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "\"hilbert modular groups, reduction algorithms\"",
"author": "Fredrik Stromberg",
"author_email": "fredrik314@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/04/9f/78edcf96ca18c723c3028304613df655c69a90e9755f7bd255410893af0d/hilbert_modular_group-0.1.2.tar.gz",
"platform": "any",
"description": "# Hilbert Modular Groups\n\nThis repository contains a python package `hilbert_modgroup` that implements algorithms \nfor Hilbert modular groups, in particular a reduction algorithm. The implementation is written in Python \nand is dependent on SageMath.\n\n## Requirements\n- SageMath v9.6+ (https://www.sagemath.org/)\n (Tested on v9.6, v9.7, v10.0 and v10.2)\n\n## Installation\n### Using sage pip\nThis package needs to be installed in the virtual environment provided by SageMath, and it is therefore necessary \nto run the following command \n```console\n$ sage -pip install --no-build-isolation hilbert-modular-group\n```\n**Note**: The `--no-build-isolation` is necessary as the compiler needs access \nto certain library files from the sage installation and SageMath itself is \ntoo large to be required as a build dependency. \nAs an alternative to this flag you can also specify the environment variable \nSAGE_LIB explicitly.\n\n### From git source\nIf the SageMath executable `sage` is in the current path you can install from source using the Makefile\n\n```console\n$ git clone https://github.com/fredstro/hilbertmodgroup.git\n$ cd hilbertmodgrup\n$ make install\n```\n\n### Docker\nIf you do not have SageMath installed, but you have docker you can use install this package\nin a docker container built and executed using e.g. `make docker-sage` or `make docker-examples`\n\n\n## Usage\nThe package can be imported and used as any other package. \nFor example, to find the reduction of the point given by [1+i,1+i] in H^2 \nwith respect to the Hilbert modular group of Q joint by square-root of 5 write: \n\n```\nsage: from hilbert_modgroup.all import *\nsage: H1=HilbertModularGroup(5)\nsage: P1=HilbertPullback(H1)\nsage: z = UpperHalfPlaneProductElement([1+I,1+I])\nsage: P1.reduce(z)\n[1.00000000000000*I, 1.00000000000000*I]\nsage: z = UpperHalfPlaneProductElement([0.25+I/2,1+I])\nsage: P1.reduce(z) # abs tol 1e-10\n[0.694427190999916 + 0.611145618000168*I, -0.309016994374947 + 1.30901699437495*I]\nsage: P1.reduce(z, return_map=True)[1]\n[-1/2*a + 1/2 1/2*a + 1/2]\n[-1/2*a + 1/2 0]\n\n```\nFor more examples see the embedded doctests (search for `EXAMPLES`) as well as\nthe `/examples` directory which contains Jupyter notebook with more extensive \nexamples corresponding to the paper\n\"Reduction Algorithms for Hilbert Modular Groups\" by F. Stromberg. (Reference to appear)\n\n## Examples\n\nThe directory `/examples` contains Jupyter notebooks with example code to illustrate the interface and functionality of this package. \nYou can either open them manually from SageMath or run one of the following commands:\n`make examples`\n`make docker-examples`\nwhich will start up a Jupyter notebook server from sagemath either locally or in a docker container. \n\n## Community Guidelines\n\n### How to Contribute?\n- Open an issue on GitHub and create a pull / merge request against the `develop` branch.\n### How to report an issue or a problem? \n- First check if the issue is resolved in the `develop` branch. If not, open an issue on GitHub. \n### How to seek help and support?\n- Contact the maintainer, Fredrik Stromberg, at: fredrik314@gmail.com (alternatively at fredrik.stromberg@nottingham.ac.uk)\n\n## Development and testing\n\nThe make file `Makefile` contains a number of useful commands that you can run using \n```console\n$ make <command>\n```\nThe following commands are run in your local SagMath environment:\n1. `build` -- builds the package in place (sometimes useful for development).\n2. `sdist` -- create a source distribution in /sdist (can be installed using `sage -pip install sdist/<dist name>`)\n3. `install` -- build and install the package in the currently active sage environment\n4. `clean` -- remove all build and temporary files\n5. `test` -- run sage's doctests (same as `sage -t src/*`)\n6. `examples` -- run a Jupyter notebook with the SageMath kernel initialised at the `/examples` directory.\n7. `tox` -- run `sage -tox` with all environments: `doctest`, `coverage`, `pycodestyle`, `relint`, `codespell`\n Note: If your local SageMath installation does not contain tox this will run `sage -pip install tox`.\n\nThe following commands are run in an isolated docker container \nand requires docker to be installed and running:\n1. `docker` -- build a docker container with the tag `hilbertmodgroup-{GIT_BRANCH}`\n2. `docker-rebuild` -- rebuild the docker container without cache\n3. `docker-test` -- run SageMath's doctests in the docker container\n4. `docker-examples` -- run a Jupyter notebook with the SageMath kernel initialised at the `/examples` directory \n and exposing the notebook at http://127.0.0.1:8888. The port used can be modified by \n5. `docker-tox` -- run tox with all environments: `doctest`, `coverage`, `pycodestyle`, `relint`, `codespell`. \n6. `docker-shell` -- run a shell in a docker container\n7. `docker-sage` -- run a sage interactive shell in a docker container\n\nThe following command-line parameters are available \n- `NBPORT` -- set the port of the notebook for `examples` and `docker-examples` (default is 8888)\n- `TOX_ARGS` -- can be used to select one or more of the tox environments (default is all)\n- `REMOTE_SRC` -- set to 0 if you want to use the local source instead of pulling from gitHub (default 1)\n- `GIT_BRANCH` -- the branch to pull from gitHub (used if REMOTE_SRC=1)\n\n### Example usage\nRun tox coverage on the branch `main` from gitHub:\n\n`make docker-tox REMOTE_SRC=1 GIT_BRANCH=main TOX_ARGS=coverage`\n\nRun doctests on the local source with local version of sage:\n\n`make tox TOX_ARGS=doctest`\n\nRun relint on the local source with docker version of sage:\n\n`make docker-tox REMOTE_SRC=0 TOX_ARGS=relint`\n\n## Development\n\n### GitHub Workflow\n\n- There are two long-lived branches `main` and `develop`.\n- The `develop` branch is used for development and can contain new / experimental features. \n- Pull-requests should be based on `develop`.\n- Releases should be based on `main`.\n- The `main` branch should always be as stable and functional as possible. In particular, merges should always happen from `develop` into `main`. \n- Git-Flow is enabled (and encouraged) with feature branches based on `develop` and hotfixes based on `main`. \n\n### GitHub Actions\n\nEach commit is tested and checked using gitHub actions with tox running:\n- `doctest` -- run all doctests\n- `coverage` -- ensure that all functions and classes are documented \n- `pycodestyle-minimal` -- ensure PEP8 style guide is followed (except we allow max line length 99)\n- `relint` -- relint against some patterns taken from the SageMath source (config file .relint.yaml)\n- `codespell` -- spellchecker\n\nTo make sure that your commit passes all tests you should `make tox` or `make docker-tox REMOTE_SRC=0` on the command line.\n\n### Versions\n\nVersioning of this project is managed by setuptools_scm.\nTo bump the version create a git tag `x.y.z` and the file \n `src/hilbert_modgroup/version.py` will then be automatically updated to contain \n```\nversion = 'x.y.z.???'\nversion_tuple = (x, y, z, '???')\n```\nwhere ??? depends on the state of the current directory. \nIf you are creating a new version to release the source directory should be clean.\n\n### PyPi\n\nTo upload new versions to PyPi: \n1. `make sdist` -- creates a source distribution `dist/hilbert_modular_group-x.y.z`\n2. `twine check dist/hilbert_modular_group-x.y.z`\n3. `twine upload --repository pypi dist/hilbert_modular_group-z.y.z`\n\n## References:\n\n- [](https://doi.org/10.21105/joss.03996)\n",
"bugtrack_url": null,
"license": "GPL v3+",
"summary": "Algorithms for Hilbert modular groups",
"version": "0.1.2",
"project_urls": {
"Bug Tracker": "https://github.com/fredstro/hilbertmodgroup/issues",
"Homepage": "https://github.com/fredstro/hilbertmodgroup",
"Source Code": "https://github.com/fredstro/hilbertmodgroup/"
},
"split_keywords": [
"\"hilbert modular groups",
" reduction algorithms\""
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "049f78edcf96ca18c723c3028304613df655c69a90e9755f7bd255410893af0d",
"md5": "71b0940ce1075020758159e871152ce5",
"sha256": "89513da23ba4ce1ee5d332e10f4b3b219ab82922388f01551f3f6314b912efa2"
},
"downloads": -1,
"filename": "hilbert_modular_group-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "71b0940ce1075020758159e871152ce5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 71664,
"upload_time": "2024-06-29T13:46:22",
"upload_time_iso_8601": "2024-06-29T13:46:22.867698Z",
"url": "https://files.pythonhosted.org/packages/04/9f/78edcf96ca18c723c3028304613df655c69a90e9755f7bd255410893af0d/hilbert_modular_group-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-29 13:46:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fredstro",
"github_project": "hilbertmodgroup",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "hilbert-modular-group"
}
JSON
