Take out the "numpy" from sympy lambdify - this automatically include…

…s scipy if available and allows compilation of special functions.

setup.cfg

@@ -10,8 +10,9 @@ zip_safe = True
 install_requires = 
   xxhash
   numpy >=1.20
+  scipy
   cython
-  sympy >=1.8
+  sympy >=1.12
   typeguard
   petsc4py >=3.20
   mpi4py

src/underworld3/__init__.py

@@ -1,11 +1,7 @@
 """## Underworld3 Python package
-
-
 `Underworld3` is a finite element, particle-in-cell geodynamics code that produces 
-mathematically self-describing models through an interface with `sympy`
-
-Underworld3 builds upon the `PETSc` parallel finite element and solver package, using their
-`petsc4py` library. 
+mathematically self-describing models through an interface with `sympy` Underworld3 builds upon the `PETSc` 
+parallel finite element and solver package, using their `petsc4py` library. 
 
 A common pattern for building `underworld3` models is to develop python scripts in notebook-friendly form
 (e.g. with `jupytext`) which are thoroughly documented through markdown descriptions. `underworld` objects 
@@ -14,12 +10,58 @@
 
 `python` scripts built this way will also be compatible with `mpirun` for parallel execution.
 
+## Documentation
+
+The underworld documentation is in two parts: the user manual / theory manual is a hand-written document that is built from this repository automatically 
+from the sources in the `Jupyterbook` directory. This api documentation is autogenerated from the code and its annotations. There are two version of 
+each documentation package that are published online. The main (stable) branch
+
+- https://underworldcode.github.io/underworld3/main/FrontPage.html
+- https://underworldcode.github.io/underworld3/main_api/index.html
+
+The development branch has similar documentation:
+
+- https://underworldcode.github.io/underworld3/development/FrontPage.html
+- https://underworldcode.github.io/underworld3/development_api/index.html
+
+
+## Building / installation
 
-.. include:: ../README.md
+Refer to the Dockerfile for uw3 build instructions.  
 
+To install from the repository
+```shell
+pip install .
+```
+
+The in-place `pip` installation may be helpful for developers (after the above)
+
+```shell
+pip install -e .
+```
+
+To clean the git repository or all files ... be careful.
+```shell
+./clean.sh
+```
+
+## Testing and documentation
+
+Run the `pytest` testing suite with
+```shell
+./test.sh
+```
+
+This API documentation is build with 
+```shell
+./docs.sh
+```
+
+Open `uw3_api_docs/index.html` to browse. 
 
 """
 
+
 import sys
 from mpi4py import MPI  # for initialising MPI
 

src/underworld3/cython/petsc_generic_snes_solvers.pyx

@@ -15,7 +15,7 @@ from underworld3.utilities._api_tools import class_or_instance_method
 
 include "petsc_extras.pxi"
 
-class Solver(uw_object):
+class SolverBaseClass(uw_object):
     r"""
     The Generic `Solver` is used to build the `SNES Solvers`
         - `SNES_Scalar`
@@ -332,7 +332,7 @@ class Solver(uw_object):
 ## Specific to dimensionality
 
 
-class SNES_Scalar(Solver):
+class SNES_Scalar(SolverBaseClass):
     r"""
     The `SNES_Scalar` solver class provides functionality for solving the scalar conservation problem in the unknown $u$:
 
@@ -852,7 +852,7 @@ class SNES_Scalar(Solver):
 # LM: this is probably not something we need ... The petsc interface is
 # general enough to have one class to handle Vector and Scalar
 
-class SNES_Vector(Solver):
+class SNES_Vector(SolverBaseClass):
     r"""
     The `SNES_Vector` solver class provides functionality for solving the vector conservation problem in the unknown $\mathbf{u}$:
 
@@ -1436,7 +1436,7 @@ class SNES_Vector(Solver):
 
 ### =================================
 
-class SNES_Stokes_SaddlePt(Solver):
+class SNES_Stokes_SaddlePt(SolverBaseClass):
     r"""
     The `SNES_Stokes` solver class provides functionality for solving the *constrained* vector
     conservation problem in the unknown $\mathbf{u}$ with the constraint parameter $\mathrm{p}$:
@@ -1463,7 +1463,7 @@ class SNES_Stokes_SaddlePt(Solver):
     physical conservation laws into this general mathematical form.
     """
 
-    class _Unknowns(Solver._Unknowns):
+    class _Unknowns(SolverBaseClass._Unknowns):
         '''Extend the unknowns with the constraint parameter'''
 
         def __init__(inner_self, owning_solver):

src/underworld3/function/_function.pyx

@@ -446,7 +446,8 @@ def evaluate( expr, np.ndarray coords=None, coord_sys=None, other_arguments=None
     elif isinstance(subbedexpr, sympy.vector.Dyadic):
         subbedexpr = subbedexpr.to_matrix(N)[0:dim,0:dim]
 
-    lambfn = lambdify( (r, varfns_symbols.values()), subbedexpr, 'numpy' )
+    lambfn = lambdify( (r, varfns_symbols.values()), subbedexpr )  
+    # Leave out modules. This is equivalent to SYMPY_DECIDE and can then include scipy if available
 
     # 5. Eval generated lambda expression
     coords_list = [ coords[:,i] for i in range(dim) ]
@@ -617,7 +618,7 @@ def evalf( expr, coords, coord_sys=None,  other_arguments=None, verbose=False):
     # elif isinstance(subbedexpr, sympy.vector.Dyadic):
     #     subbedexpr = subbedexpr.to_matrix(N)[0:dim,0:dim]
 
-    lambfn = lambdify( (r, varfns_symbols.values()), subbedexpr, 'numpy' )
+    lambfn = lambdify( (r, varfns_symbols.values()), subbedexpr )
 
     # 5. Eval generated lambda expression
     coords_list = [ coords[:,i] for i in range(dim) ]