added an example, updated readme, fixed deprecations

.gitignore

@@ -1,5 +1,7 @@
+.ipynb_checkpoints
 __pycache__
 *.pyc
+venv/
 build/
 dist/
 magma_kernel.egg-info/

README.md

@@ -0,0 +1,75 @@
+# Magma Jupyter Kernel
+
+A simple Jupyter kernel for the Magma computer algebra system.
+
+## Requirements
+
+-   Magma must be installed and runnable using the standard path, i.e., typing the command `magma`
+    will run Magma.
+
+-   Jupyter running on Python 3.
+
+## Installation
+
+If `pip` and `python` point to their Python 3 versions, you can install the kernel as a user with
+the commands:
+
+```sh
+pip install git+https://git.phc.dm.unipi.it/phc/magma_kernel
+python -m magma_kernel.install
+```
+
+On some systems, you may need to use `pip3` and `python3` instead.
+
+### Using a remote magma installation
+
+If the magma instance is on a remote machine, you can add an ssh key to the remote machine and add
+the following function in your `.bashrc` or `.zshrc`
+
+```sh
+function magma() {
+    ssh -qt user@remote "magma $*"
+}
+```
+
+Then, you can use it "locally" with the following command:
+
+```sh
+$ magma
+```
+
+## Usage
+
+To use the kernel, run one of the following commands
+
+```sh
+# Select "New" -> "Notebook" and then in the new tab select "Magma" as the kernel
+jupyter notebook
+
+# Or run the console with the Magma kernel (still better than pure magma)
+jupyter console --kernel magma
+```
+
+## Development
+
+To install the kernel in development mode, clone the repository and run
+
+```sh
+# Create a virtual environment
+python -m venv venv
+source venv/bin/activate
+
+# Locally install the kernel
+pip install -r requirements.txt
+python -m magma_kernel.install
+```
+
+## Credits
+
+This code is based on a Magma kernel for IPython written by [@nbruin](https://github.com/nbruin),
+which was in turn based on [@cgranade/magma_kernel](https://github.com/cgranade/magma_kernel) the
+Bash example kernel by Thomas Kluyver. Improvements made in the current version include:
+
+-   Removed some deprecated function usages
+
+-   Added a `requirements.txt` file

README.rst

@@ -1,32 +0,0 @@
-A simple Jupyter kernel for the Magma computer algebra system
-
-This kernel requires that Magma is installed and runnable using the
-standard path, i.e., that typing the command ``magma`` will run magma.
-Furthermore, it requires Jupyter running on Py3.
-
-If ``pip`` and ``python`` point to their Py3 versions, you can install the 
-kernel as a user with the commands::
-
-    pip install git+https://github.com/nbruin/magma_kernel --user
-    python -m magma_kernel.install
-
-On some systems you may need to use ``pip3`` and ``python3`` instead::
-
-    pip3 install git+https://github.com/nbruin/magma_kernel --user
-    python3 -m magma_kernel.install
-
-To use it, run one of:
-
-.. code:: shell
-
-    jupyter notebook
-    # In the notebook interface, select Magma from the 'New' menu
-    jupyter qtconsole --kernel magma
-    jupyter console --kernel magma
-
-This code is based on a Magma kernel for IPython written by Christopher 
-Granade, which was in turn based on the Bash example kernel by Thomas 
-Kluyver. Improvements made in the current version include Tab 
-completion, processing of help requests by returning an appropriate 
-help query URL for Magma online documentation, and the reporting of 
-partial output.

examples/lomb.m

@@ -0,0 +1,174 @@
+/******
+Elementary approach to enumerating groups of order 2^n, n \leq 6
+*******/
+
+/*
+Compute the Cayley embedding of a finite group G
+*/
+function CayleyEmbedding(G)
+	// Get the order of the group
+	n := #G;
+
+	// Define the symmetric group on n elements
+	S := SymmetricGroup(n);
+	
+	// Get the elements of G
+	elements := [g : g in G];
+
+	// Create a map from G to S_n
+	CayleyMap := hom<G -> S | g :-> S![Index(elements, g * elements[i]) : i in [1..n]]>;
+
+	return Image(CayleyMap), CayleyMap;
+end function;
+
+/*
+Construct the "double" of a permutation sigma
+*/
+function DoublePermutation(sigma)
+	n := Degree(Parent(sigma));
+	S2n := Sym(2*n);
+	L := [i^sigma : i in [1..n]] cat [i^sigma + n : i in [1..n]];
+	
+    return S2n!L;
+end function;
+
+/*
+Construct the "double" of a group G
+*/
+function DoubleGroup(G)
+	H := CayleyEmbedding(G);
+	n := #H;
+	HDouble := sub< Sym(2*n) | [ DoublePermutation(h) : h in Generators(H) ] >;
+	
+    return HDouble;
+end function;
+
+
+/*
+Given a group G, construct a list of groups H
+such that G < H with index 2, and up to isomorphism,
+every group H with this property appears in the list.
+
+The first version is elementary; the second uses the
+correspondence theorem for subgroups; and the third
+one optimises by not repeating subgroups that are
+obviously conjugate to one another and only considering
+a 2-Sylow subgroup of the normaliser.
+*/
+function ConstructDoubleCovers(G)
+	GDouble := DoubleGroup(G);
+	N := Normaliser( Sym(2*#G), GDouble );
+	subs := Subgroups(N : OrderEqual := 2*#G );
+	subs := [sub`subgroup : sub in subs];
+	subs := [H : H in subs | GDouble subset H ];
+	
+    return subs;
+end function;
+
+function ConstructDoubleCovers2(G)
+	GDouble := DoubleGroup(G);
+	N := Normaliser( Sym(2*#G), GDouble );
+	Quoziente, Proiezione := N/GDouble;
+	Sezione := Proiezione^(-1);
+	Els2 := [q : q in Quoziente | Order(q) eq 2];
+	subs := [ sub< N | GDouble, Sezione(q) > : q in Els2 ];
+	
+    return subs;
+end function;
+
+function ConstructDoubleCovers3(G)
+	"Computing double";
+	time GDouble := DoubleGroup(G);
+	"Computing normaliser";
+	time N := Normaliser( Sym(2*#G), GDouble );
+	"Computing Sylow subgroup";
+	Sylow2 := SylowSubgroup(N, 2);
+	"Computing quotient";
+	"Order of quotient:", #Sylow2 / #GDouble;
+	time Quoziente, Proiezione := Sylow2/GDouble;
+	"Computing section";
+	time Sezione := Proiezione^(-1);
+	"Computing elements of order 2 in the quotient";
+	time Els2 := Subgroups(Quoziente : OrderEqual := 2);
+	"Computing subgroups";
+	time subs := [ sub< N | GDouble, Sezione(q`subgroup) > : q in Els2 ];
+	
+    return subs;
+end function;
+
+
+/*
+Given a list L of groups, returns a list L' that contains
+every isomorphism class of groups in L precisely once
+*/
+function FilterDuplicates(list)
+	CleanList := [];
+	for H in list do
+		test := true;
+		for H2 in CleanList do
+			if test then
+				test := test and not IsIsomorphic(H, H2);
+			end if;
+		end for;
+		if test then
+			CleanList := CleanList cat [H];
+		end if;
+	end for;
+	
+    return CleanList;
+end function;
+
+function FilterDuplicatesFast(list)
+	CleanList := [];
+	CleanNames := [];
+	for H in list do
+		if not GroupName(H) in CleanNames then
+			CleanList := CleanList cat [H];
+			CleanNames := CleanNames cat [GroupName(H)];
+		end if;
+	end for;
+	
+    return CleanList;
+end function;
+
+
+/*
+Given a list L of groups [G_i], returns a list L' = [H_j]
+where each H_j contains some G_i with index 2, every
+group with this property appears in L', and L' contains no
+duplicates up to isomorphism.
+*/
+function DoubleListSlow(L)
+	LNew := [];
+	for G in L do
+		dc := ConstructDoubleCovers(G);
+		dc := FilterDuplicates(dc);
+		LNew := LNew cat dc;
+	end for;
+	
+    return FilterDuplicates(LNew);
+end function;
+
+function DoubleList(L)
+	LNew := [];
+	for G in L do
+		time dc := ConstructDoubleCovers3(G);
+		time dc := FilterDuplicatesFast(dc);
+		LNew := LNew cat dc;
+	end for;
+	
+    return FilterDuplicatesFast(LNew);
+end function;
+
+
+list2 := [CyclicGroup(2)];
+time list4 := DoubleList(list2);
+time list8 := DoubleList(list4);
+time list16 := DoubleList(list8);
+time list32 := DoubleList(list16);
+time list64 := DoubleList(list32);
+
+assert #list32 eq NumberOfSmallGroups(32);
+assert #list64 eq NumberOfSmallGroups(64);
+
+

magma_kernel/install.py

@@ -21,7 +21,7 @@ def install_my_kernel_spec(user=True, prefix=None):
         # TODO: Copy resources once they're specified
 
         print('Installing IPython kernel spec')
-        KernelSpecManager().install_kernel_spec(td, 'magma', user=user, replace=True, prefix=prefix)
+        KernelSpecManager().install_kernel_spec(td, 'magma', user=user, prefix=prefix)
 
 def _is_root():
     try:

requirements.txt

@@ -0,0 +1,96 @@
+anyio==4.6.2.post1
+argon2-cffi==23.1.0
+argon2-cffi-bindings==21.2.0
+arrow==1.3.0
+asttokens==2.4.1
+async-lru==2.0.4
+attrs==24.2.0
+babel==2.16.0
+beautifulsoup4==4.12.3
+bleach==6.2.0
+certifi==2024.8.30
+cffi==1.17.1
+charset-normalizer==3.4.0
+comm==0.2.2
+debugpy==1.8.9
+decorator==5.1.1
+defusedxml==0.7.1
+executing==2.1.0
+fastjsonschema==2.20.0
+fqdn==1.5.1
+h11==0.14.0
+httpcore==1.0.7
+httpx==0.27.2
+idna==3.10
+ipykernel==6.29.5
+ipython==8.29.0
+ipywidgets==8.1.5
+isoduration==20.11.0
+jedi==0.19.2
+Jinja2==3.1.4
+json5==0.9.28
+jsonpointer==3.0.0
+jsonschema==4.23.0
+jsonschema-specifications==2024.10.1
+jupyter==1.1.1
+jupyter-console==6.6.3
+jupyter-events==0.10.0
+jupyter-lsp==2.2.5
+jupyter_client==8.6.3
+jupyter_core==5.7.2
+jupyter_server==2.14.2
+jupyter_server_terminals==0.5.3
+jupyterlab==4.2.6
+jupyterlab_pygments==0.3.0
+jupyterlab_server==2.27.3
+jupyterlab_widgets==3.0.13
+-e git+https://github.com/nbruin/magma_kernel@4418bd79d1756c7558374086b6ef47b4e18207c2#egg=magma_kernel
+MarkupSafe==3.0.2
+matplotlib-inline==0.1.7
+mistune==3.0.2
+nbclient==0.10.0
+nbconvert==7.16.4
+nbformat==5.10.4
+nest-asyncio==1.6.0
+notebook==7.2.2
+notebook_shim==0.2.4
+overrides==7.7.0
+packaging==24.2
+pandocfilters==1.5.1
+parso==0.8.4
+pexpect==4.9.0
+platformdirs==4.3.6
+prometheus_client==0.21.0
+prompt_toolkit==3.0.48
+psutil==6.1.0
+ptyprocess==0.7.0
+pure_eval==0.2.3
+pycparser==2.22
+Pygments==2.18.0
+python-dateutil==2.9.0.post0
+python-json-logger==2.0.7
+PyYAML==6.0.2
+pyzmq==26.2.0
+referencing==0.35.1
+requests==2.32.3
+rfc3339-validator==0.1.4
+rfc3986-validator==0.1.1
+rpds-py==0.21.0
+Send2Trash==1.8.3
+setuptools==75.6.0
+six==1.16.0
+sniffio==1.3.1
+soupsieve==2.6
+stack-data==0.6.3
+terminado==0.18.1
+tinycss2==1.4.0
+tornado==6.4.2
+traitlets==5.14.3
+types-python-dateutil==2.9.0.20241003
+uri-template==1.3.0
+urllib3==2.2.3
+wcwidth==0.2.13
+webcolors==24.11.1
+webencodings==0.5.1
+websocket-client==1.8.0
+widgetsnbextension==4.0.13

setup.py

@@ -1,7 +1,7 @@
 from setuptools import setup, find_packages
 
 def readme():
-    with open('README.rst') as f:
+    with open('README.md') as f:
         return f.read()
 
 setup(