Updating documentation and tidying after new build system

.github/workflows/build_deploy_wheels.yml

@@ -26,7 +26,7 @@ jobs:
           - [ macos-11, macosx, arm64] # cross compiled
           - [ windows-2019, win, AMD64 ]
 
-        python: [[ "cp37", "3.7" ], [ "cp38", "3.8" ], [ "cp39", "3.9" ], [ "cp310", "3.10" ]]
+        python: [[ "cp37", "3.7" ], [ "cp38", "3.8" ], [ "cp39", "3.9" ], [ "cp310", "3.10" ], [ "cp311", "3.11" ]]
 
     name: Build wheel for ${{ matrix.python[0] }}-${{ matrix.buildplat[1] }} ${{ matrix.buildplat[2] }}
 

.github/workflows/test_unit_and_examples.yml

@@ -89,7 +89,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, macos-latest]
+        os: [ubuntu-latest, macos-latest, windows-latest]
         python-version: [ "3.7", "3.8", "3.9", "3.10" ]
 
     steps:
@@ -119,9 +119,9 @@ jobs:
           brew reinstall gfortran
           brew install ngspice boost suite-sparse
 
-      - name: Install system dependencies in Windows
-        if: matrix.os == 'windows-latest'
-        run: choco install ngspice
+#      - name: Install system dependencies in Windows
+#        if: matrix.os == 'windows-latest'
+#        run: choco install ngspice
 
       - name: Install Python dependecies
         run: |
@@ -141,8 +141,14 @@ jobs:
         run: |
           python -m devpy build -- -Dwith_pdd=true -Dinstall_test=true
 
-      - name: Unit and functional tests
+      - name: Unit and functional tests (MacOS and Linux)
+        if: matrix.os != 'windows-latest'
         env:
           SOLCORE_SPICE: ngspice
         run: |
           python -m devpy test -- -r a -v solcore/tests/test_examples.py -n "auto"
+
+      - name: Unit and functional tests (Windows)
+        if: matrix.os == 'windows-latest'
+        run: |
+          python -m devpy test -- -r a -v solcore/tests/test_examples.py -n "auto"

.pre-commit-config.yaml

@@ -3,4 +3,10 @@ repos:
   rev: 0.6.1
   hooks:
     - id: nbstripout
-      files: ".ipynb"
+      files: ".ipynb"
+
+- repo: https://github.com/pycqa/flake8
+  rev: 6.0.0
+  hooks:
+    - id: flake8
+      additional_dependencies: [Flake8-pyproject]

docs/source/Examples/example_MJ_efficiency_map.rst

@@ -27,9 +27,10 @@ Example of using the DB solver to calculate the efficiency map of a 3J solar cel
 
     # This function assembles the solar cell and calculates the IV cruve
     def solve_MJ(EgBot, EgMid, EgTop):
-        db_junction0 = Junction(kind='DB', T=T, Eg=EgBot, A=1, R_shunt=np.inf, n=3.5)
-        db_junction1 = Junction(kind='DB', T=T, Eg=EgMid, A=1, R_shunt=np.inf, n=3.5)
-        db_junction2 = Junction(kind='DB', T=T, Eg=EgTop, A=1, R_shunt=np.inf, n=3.5)
+        db_junction0 = Junction(kind='DB', T=T, Eg=EgBot, A=1, R_shunt=np.inf, n=1)
+        db_junction1 = Junction(kind='DB', T=T, Eg=EgMid, A=1, R_shunt=np.inf, n=1)
+        db_junction2 = Junction(kind='DB', T=T, Eg=EgTop, A=1, R_shunt=np.inf, n=1)
+        # n is the ideality factor of the diode. It is 1 for a perfect diode, but can be higher for a real diode.
 
         my_solar_cell = SolarCell([db_junction2, db_junction1, db_junction0], T=T, R_series=0)
 

docs/source/Installation/Solcore_on_Windows.md

@@ -1,14 +1,10 @@
 Solcore on Windows 10
 =====================
-The Python part of Solcore, which is the majority, should work under Windows with no problems. However, we have had some
-trouble trying to make the parts and complements that require compilation to work properly (the PDD solver, S4, SMARTS 
-and SPICE). For those who need to use those tools and encounter issues on Windows, please follow the instructions below. 
-
-Note that in principle, out of the packages listed above (the PDD solver, S4, SMARTS and SPICE), all can be
-installed on Windows **except S4**, which to date we have not been able to produce Windows installation instructions for. 
-To compile the PDD, you need to do [a few extra steps](compilation.md) to get a suitable compiler working. Steps
-for (optionally) installing SMARTS are given below.
-S4 is only required to use the rigorous coupled-wave analysis (RCWA) functionality in Solcore, used to calculate diffraction
+
+These instructions should be relevant only if you are a Windows user who would like to use Solcore's rigorous coupled-wave
+analysis (RCWA) functionality, requiring the S4 package, for which we unfortunately do not have installation instructions 
+for Windows. All other parts of Solcore, and the optional SMARTS and SPICE dependencies, can be installed on Windows. S4 
+is only required to use the rigorous coupled-wave analysis (RCWA) functionality in Solcore, used to calculate diffraction
 from periodic structures (e.g. diffraction gratings, photonic crystals). Thus, if you do not need this functionality, you 
 can stick with Windows.
 

docs/source/Installation/installation.rst

@@ -15,73 +15,63 @@ Once you are ready to install it in your own machine, go to the next section.
 
 Installing Solcore
 ^^^^^^^^^^^^^^^^^^
+The only requirement for install Solcore is having Python version 3.7 or higher (Python 3.8 or higher if you are installing
+on a MacOS device with an ARM/Apple M1 chip). Installing Solcore (version 5.9 onwards) should be as easy as running the
+following command in your terminal::
 
-Solcore is written mostly in Python, but the Poisson-Drift-diffusion (PDD) solver is written in Fortran to make it more efficient,
-and the RCWA (rigorous coupled-wave analysis) solver uses the package S4 which is written in C++.
-The following instructions are expected to work in most systems, but check the sections below for OS specific instructions and caveats.
-In order to install Solcore in your computer, you will need the following:
+    pip install solcore
 
-- Python >3.7
-- pip
-- setuptools
-- :doc:`a suitable Fortran compiler (only needed for the PDD solver) <compilation>`
-- :doc:`the S4 package (only needed for RCWA functionality) <s4_installation>`
 
-*Pip* is normally part of the standard Python installation, but you might need to
-install it. You also need to make sure the *setuptools* and *wheel* packages are
-available. To make sure these packages are installed and up to date, run::
+This will download Solcore form the PyPI repository and install the package within the active Python environment. Depending
+on your operating system/Python installation you may need to use `pip3` instead of `pip`. And that's all! Solcore should
+be available to be used as with any Python package::
 
-    pip install -U pip setuptools wheel
+    >>> import solcore
+
+        Welcome to Solcore - version 5.6.0
+        Copyright (c) 2018, Imperial College, London All rights reserved.
+        Software released under the GNU Lesser General Public License.
 
-Now, installing Solcore should be as easy as writing in the terminal::
+Installation details
+^^^^^^^^^^^^^^^^^^^^
 
-    pip install solcore
+Solcore is written mostly in Python, but the Poisson-Drift-diffusion (PDD) solver is written in Fortran to make it more efficient,
+and the RCWA (rigorous coupled-wave analysis) solver uses the package `S4 <https://web.stanford.edu/group/fan/S4/>`_ which
+is written in C++. Solcore uses pre-built
+binary wheels for the PDD solver to make installation as easy as possible (these are built for Windows, Linux, and MacOS,
+including for ARM/M1 chip architectures).
 
-This will download Solcore form the PyPI repository and install the package within the
-Python packages tree. **From Solcore v5.8.1 this will also install the PDD solver if you
-are in Linux or Windows**.
+The package S4, which supports Solcore's RCWA capabilities (used to calculate the optical effects of diffraction grating
+and other periodic structures) is not installed automatically. If you want to use these features you will need to install it
+yourself :doc:`as described here <s4_installation>`. If you would like to use S4 on Windows please
+:doc:`see the suggestions here <Solcore_on_Windows>`.
 
-If you are in MacOS - or if there are no binary wheels for yous
-specific Python version and system architecture combination -, this command will *NOT*
-install the PDD solver, for which you need a suitable Fortran compiler :doc:`(read this
-to install your Fortran compiler) <compilation>`. Assuming you have a Fortran compiler
-correctly installed and configured, you can install Solcore with the PDD solver by
-doing::
+If you would like to compile the PDD solver locally (**not necessary in general**), you will need to have a
+:doc:`a suitable Fortran compiler (only needed for the PDD solver) <compilation>`. Assuming you have a Fortran compiler
+correctly installed and configured, you can install Solcore with the PDD solver by doing::
 
     pip install solcore
     pip install --no-deps --force-reinstall --install-option="--with_pdd" solcore
 
-**NOTE**: Pip passes the --install-option to all the dependencies of the package and therefore the installation will fail since those dependencies do not have the option "--with_pdd". That is the reason why, for now, Solcore needs to be installed twice: the first one to install Solcore normally with all the dependencies and the second one re-installs Solcore with PDD support. 
-
-And that's all! Solcore should be available to be used as with any Python package::
+**NOTE**: Pip passes the --install-option to all the dependencies of the package and therefore the installation will fail
+since those dependencies do not have the option "--with_pdd". That is the reason why, for now, Solcore needs to be installed
+twice: the first one to install Solcore normally with all the dependencies and the second one re-installs Solcore with PDD support.
 
-    >>> import solcore
-
-        Welcome to Solcore - version 5.6.0
-        Copyright (c) 2018, Imperial College, London All rights reserved.
-        Software released under the GNU Lesser General Public License.
+Installing from source
+^^^^^^^^^^^^^^^^^^^^^^
 
-Alternative installation method
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Alternatively, you can `download the source from the Solcore GitHub repository <https://github.com/dalonsoa/solcore5>`_, either using 'git' or as a zip file using one of the links on the right. If you want to install it, unpack it and run from the directory where *setup.py* is located (you still need *pip*, *setuptools* and *numpy* installed; see above)::
+Alternatively, you can `download the source from the Solcore GitHub repository <https://github.com/dalonsoa/solcore5>`_,
+either using `git clone` or as a zip file using one of the links on the right. If you want to install it, unpack it and
+run from the directory where *setup.py* is located::
 
     pip install .
 
 or::
 
     pip install . --install-option="--with_pdd"
 
-If you want to test first if Solcore will work in your computer, without actually installing it, or if you want to become a developer and therefore you need to have it in a more accessible place, you can test if Solcore works with::
-
-    python setup.py test
-
-This will also install the Solcore dependencies and run a few tests that probe several of the Solcore tools. If it fails, it will indicate which parts failed to work and why, and you could try to solve them. At the moment, this only cover some of Solcore's functionality, but it will be expanded with time. The tests related to the PDD solver will fail, of course, since the PDD solver will not be compiled. If you want to test everything, compiling the the PDD solver, just run::
-
-    python setup.py test --with_pdd
-
-Install in development mode
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Installing in development mode
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 If you are planning to develop Solcore further, you would want to have all the files in an accessible place but still being able to use the package from other places and examples, behaving as if it were truly installed. For this, install Solcore in development mode. `Download the source from the Solcore GitHub repository <https://github.com/dalonsoa/solcore5>`_ as above and then::
 
@@ -105,7 +95,9 @@ After installing Solcore (or even without installing it), there are a few things
 - :doc:`Windows 10 <Solcore_on_Windows>`
 - :doc:`Mac OS X <Solcore_on_MacOSX>`
 
-1. **Create a user configuration file:** The first time Solcore is run, it will create a hidden folder in your user directory. This folder will contain the local configuration and will store custom materials and other parameters. You can customize the location of by setting the environmental variable :code:`SOLCORE_USER_DATA`. You can check the current configuration with:
+1. **Create a user configuration file:** The first time Solcore is run, it will create a hidden folder in your user directory.
+This folder will contain the local configuration and will store custom materials and other parameters. You can customize the
+location of by setting the environmental variable :code:`SOLCORE_USER_DATA`. You can check the current configuration with:
 
 .. code:: python
 
@@ -114,7 +106,10 @@ After installing Solcore (or even without installing it), there are a few things
 
 You can find all the functionality of the :code:`config` object in `The config_tools`_.
 
-2. **Check Solcore examples:** This is the fastest way of getting started. These examples include all the scripts used in the main Solcore paper in the `Journal of Computational Electronics (2018) <https://doi.org/10.1007/s10825-018-1171-3>`_ and a few others to explore other functionality. We hope to increase the number and usefulness of these examples over time. You can try the examples directly using `MyBinder.org <https://mybinder.org/v2/gh/qpv-research-group/solcore5/deployment>`_.
+2. **Check Solcore examples:** This is the fastest way of getting started. These examples include all the scripts used in
+the main Solcore paper in the `Journal of Computational Electronics (2018) <https://doi.org/10.1007/s10825-018-1171-3>`_
+and a few others to explore other functionality. We hope to increase the number and usefulness of these examples over
+time. You can try the examples directly using `MyBinder.org <https://mybinder.org/v2/gh/qpv-research-group/solcore5/deployment>`_.
 
 3. **Set the location of a SPICE executable and the SMARTS folder:** You will need to do this if you want to use those tools::
 
@@ -126,9 +121,15 @@ You can find all the functionality of the :code:`config` object in `The config_t
 	config.smarts('/path/to/the/SMARTS/folder')
 
 
-4. **Installing S4:** The rigorous-coupled wave analysis (RCWA) solver S4, created by the Stanford University, needs to be installed separately using `the fork by Phoebe Pearce <http://github.com/phoebe-p/S4>`_. The original version **does not work** with Python 3.x, only with Python 2. You can find more information about the solver in the `project webpage <http://web.stanford.edu/group/fan/S4/>`_. An example of its use with Solcore is included in the examples folder :doc:`here </Examples/example_optics_comparison>`.
+4. **Installing S4:** The rigorous-coupled wave analysis (RCWA) solver S4, created by the Stanford University, needs to
+be installed separately using `the fork by Phoebe Pearce <http://github.com/phoebe-p/S4>`_. The original version
+**does not work** with Python 3.x, only with Python 2. You can find more information about the solver in the
+`project webpage <http://web.stanford.edu/group/fan/S4/>`_. An example of its use with Solcore is included in the
+examples folder :doc:`here </Examples/example_optics_comparison>`.
 
-5. **Getting specific information about Solcore:** Even though the documentation "should" be more complete, you can get information about any object in python (including any Solcore function, module and package) using the :code:`help` built-in function, for example::
+5. **Getting specific information about Solcore:** Even though the documentation "should" be more complete, you can get
+information about any object in python (including any Solcore function, module and package) using the :code:`help` built-in
+function, for example::
 
 .. code:: python
 
@@ -141,14 +142,21 @@ Problems with the installation
 
 There are several things that can go wrong in the above description, specially in Windows.
 
-1. **The tests associated with the Poisson-Drift-Diffusion solver fail**: This is usually the result of not having a Fortran compiler installed in your system, not being correctly configured or having a temperamental F2PY version, the tool - included in numpy - that makes Fortran code accesible from Python. Please, make sure you follow all the steps indicated in the :doc:`Fortran compiler section <compilation>` and above to have the PDD solver up and running.
+1. **The tests associated with the Poisson-Drift-Diffusion solver fail**: This is usually the result of not having a
+Fortran compiler installed in your system, not being correctly configured or having a temperamental F2PY version,
+the tool - included in numpy - that makes Fortran code accesible from Python. Please, make sure you follow all the
+steps indicated in the :doc:`Fortran compiler section <compilation>` and above to have the PDD solver up and running.
 
-2. **Some of the dependencies fail to install**: That is rarely the case, as all dependencies are in the main Python repositories. However, there might be issues with Numpy, Matplotlib and Scipy. Depending on your Python distribution, some of these packages might need to be compiled and it is often easy to get them as a scientific bundle. You can check `Anaconda <https://www.continuum.io/downloads>`_ which provides all these packages together already configured for the correct OS.
+2. **Some of the dependencies fail to install**: That is rarely the case, as all dependencies are in the main
+Python repositories. However, there might be issues with Numpy, Matplotlib and Scipy. Depending on your Python
+distribution, some of these packages might need to be compiled and it is often easy to get them as a scientific bundle.
+You can check `Anaconda <https://www.continuum.io/downloads>`_ which provides all these packages together already
+configured for the correct OS.
 
 3. **The PDD solver throws an error, even though I installed it and the installation appeared to be successful**:
-   This can happen if you are trying to call PDD functions when the solcore5 directory (downloaded from GitHub) is
-   the current working directory. Try calling the functions from a different working directory (by e.g. copying the file you
-   are trying to run to a different directory) and seeing if the error persists.
+This can happen if you are trying to call PDD functions when the solcore5 directory (downloaded from GitHub) is
+the current working directory. Try calling the functions from a different working directory (by e.g. copying the file you
+are trying to run to a different directory) and seeing if the error persists.
 
 The config_tools
 ^^^^^^^^^^^^^^^^