Merge branch 'develop' of github.com:ifilot/pyqint into develop

Author: ifilot

.github/workflows/build_wheels.yml

@@ -46,7 +46,7 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Build wheels
-        uses: pypa/cibuildwheel@v2.17.0
+        uses: pypa/cibuildwheel@v3.2.0
 
       - uses: actions/upload-artifact@v4
         with:

.gitignore

@@ -152,4 +152,4 @@ anaconda-upload/*
 
 # managlyph .abo files
 *.abo
-.vscode
+.vscode

conda_build_config.yaml

@@ -4,12 +4,14 @@ python:
   - 3.10
   - 3.11
   - 3.12
+  - 3.13
 numpy:
   - 1.22
   - 1.22
   - 1.23
   - 1.26
   - 1.26
+  - 2.1
 zip_keys:
   - python
   - numpy

docs/installation.rst

@@ -6,60 +6,88 @@ Installation
 
 .. tip::
     For Windows users with relatively little experience with Python, we warmly
-    recommend to use the `Anaconda distribution <https://www.anaconda.com/products/distribution>`_.
-    Anaconda is an all-in-one package containing the Python compiler,
-    an integrated desktop environment (Spyder) and plenty of useful Python
-    packages such as numpy and matplotlib.
+    recommend the `Anaconda distribution <https://www.anaconda.com/products/distribution>`_.
+    Anaconda provides Python, an integrated desktop environment (Spyder), and
+    widely used packages such as NumPy and Matplotlib.
 
-:program:`PyQInt` is distributed via both Anaconda package as well as PyPI. For
-Windows, it is recommended to install :program:`PyQInt` via Anaconda, while
-for Linux, we recommend to use PyPI.
+:program:`PyQInt` is available via both Conda and PyPI. We recommend **using an
+isolated environment** rather than installing into the global Python or Conda
+``base`` environment. This avoids package conflicts and makes your setup easier
+to reproduce.
 
-Windows / Anaconda
-------------------
+Why environments?
+-----------------
+An environment keeps the packages for a project separate from the rest of your
+system (and from other projects). This prevents accidental upgrades or conflicts
+that can break existing setups. It also makes it easy to remove the environment
+later without touching your system-wide Python. For these reasons, installing
+into Conda’s ``base`` environment is discouraged.
 
-To install :program:`PyQInt` under Windows, open an Anaconda Prompt window
-and run::
+Windows / Conda (recommended)
+-----------------------------
 
-    conda install -c ifilot pyqint
+Create and activate a fresh Conda environment, then install :program:`PyQInt`::
+
+    conda create -n eoesc-env -c ifilot pyqint
+    conda activate eoesc-env
 
 .. note::
-    Sometimes Anaconda is unable to resolve the package dependencies. This can
-    be caused by a broken environment. An easy solution is to create a new
-    environment. See the "Troubleshooting" section at the end of this page
-    for more information.
+    If you would like to use :program:`PyQInt`’s **isosurface functionality**,
+    you will also need the optional package ``pytessel``. You can install it
+    together with :program:`PyQInt`::
 
-Linux / PyPI
-------------
+        conda create -n eoesc-env -c ifilot pyqint pytessel
+        conda activate eoesc-env
 
-To install :program:`PyQInt` systemwide, run::
+    or add it later with::
 
-    sudo pip install pyqint
+        conda install -c ifilot pytessel
 
-or to install :program:`PyQInt` only for the current user, run::
+Optionally install the Spyder IDE and common scientific packages::
+
+    conda install spyder matplotlib scipy pandas openpyxl
 
+Linux / macOS / PyPI (recommended via virtual environment)
+----------------------------------------------------------
+
+Use Python’s built-in virtual environments to isolate your installation::
+
+    python3 -m venv venv
+    source venv/bin/activate
+    pip install --upgrade pip
     pip install pyqint
 
-Troubleshooting
----------------
+Optional extra for **isosurface functionality**::
 
-The Anaconda packaging system can sometimes be quite finicky and sometimes
-packages conflict with each other. A way to work around this issue is to create
-a separate environment and only use that environment for the electronic
-resources associated with this project.
+    pip install pytessel
 
-To create the new environment (called eoesc-env), run::
+To leave the environment, run::
 
-    conda create -n eoesc-env python=3.11
+    deactivate
 
-Next, open the environment with::
+Alternative (single-user install without a virtual environment)
+---------------------------------------------------------------
 
-    conda activate eoesc-env
+If you prefer not to create a virtual environment, you can install for the
+current user only (no system-wide changes)::
 
-and install the required packages::
+    pip install --user pyqint
 
-    conda install -c ifilot pyqint pytessel
+.. warning::
+    We **do not recommend** using ``sudo pip install ...``. Installing packages
+    with administrative privileges can overwrite or conflict with system Python
+    components and may break tools your operating system relies on.
 
-Finally, you can install the IDE Spyder using::
+Troubleshooting
+---------------
 
-    conda install spyder matplotlib scipy pandas openpyxl
+- If Conda reports conflicts during installation, it usually means the active
+  environment has incompatible packages. Creating a fresh environment (as shown
+  above) is the most reliable fix.
+
+- If ``pip`` cannot find the package or fails due to permissions, ensure your
+  virtual environment is activated, or use ``--user`` for a local user install.
+
+- If Spyder does not see the environment, launch Spyder **from within** the
+  activated environment (``conda activate eoesc-env`` then ``spyder``), or
+  configure the interpreter path in Spyder’s preferences.

docs/user_interface.rst

@@ -843,8 +843,10 @@ Constructing isosurfaces
 ------------------------
 
 .. note::
-    Isosurface generation requires the :program:`PyTessel` package to be
-    installed. More information can be found `here <https://ifilot.github.io/pytessel/>`_.
+    * Isosurface generation requires the :program:`PyTessel` package to be
+      installed. Make sure you have installed :program:`PyTessel` alongside 
+      :program:`PyQInt`. For more details, see the :ref:`installation`.
+    * Optionally, have a look at `PyTessel's documentation <https://ifilot.github.io/pytessel/>`_.
 
 .. code-block:: python