Merge pull request #210 from qpv-research-group/examples_docs

Update documentation

.gitignore

@@ -127,4 +127,7 @@ dmypy.json
 .idea/
 
 # VS Code
-.vscode/
+.vscode/
+
+# macOS
+.DS_Store

docs/source/Examples/custom_materials_example.rst

@@ -18,21 +18,10 @@ Setting up the options for and defining custom materials
  import numpy as np
  import os
 
- # first we need to tell Solcore some things about where to put custom materials. for this,
- # we use the add_source function from config_tools, although we could also manually edit
- # the solcore configuration file (which should be in your home directory).
- # You need to add two things to the config file: where to put the n and k data for new
- # materials added to the database, and where to put the other parameters (these can all
- # go in the same file).
-
- home_folder = os.path.expanduser('~')
- custom_nk_path = os.path.join(home_folder, 'Solcore/custommats')
- nk_db_path = os.path.join(home_folder, 'Solcore/NK.db')
- param_path = os.path.join(home_folder, 'Solcore/custom_params.txt')
-
- add_source('Others', 'custom_mats', custom_nk_path)
- add_source('Others', 'nk', nk_db_path)
- add_source('Parameters', 'custom', param_path)
+ # When adding custom materials - or getting the refractive index database - the
+ # information will be stored in the Solcore's users folder. These can be setup by setting
+ # the SOLCORE_USER_DATA environmental variable to your prefered location or, by default,
+ # it will be in your home directory, in a directory called .solcore.
 
  # EXAMPLE 1
 
@@ -43,6 +32,10 @@ Setting up the options for and defining custom materials
  # the parameters in SiGeSn_params.txt have been copied directly from Ge.
  create_new_material('SiGeSn', 'SiGeSn_n.txt', 'SiGeSn_k.txt', 'SiGeSn_params.txt')
 
+ # Note that the final argument, the parameter file, is optional - if you do not
+ # provide it, a material will be added with optical constants only, so it can be
+ # used for optical calculations.
+
  # can now create an instance of it like any Solcore material
  SiGeSn = material('SiGeSn')()
 

docs/source/Examples/example_3J_with_DA_solver.rst

@@ -14,7 +14,6 @@ Example of a 3J solar cell calculated with the DA solver
 
 .. code-block:: Python
 
- import os
  import numpy as np
  import matplotlib.pyplot as plt
 
@@ -28,7 +27,8 @@ Example of a 3J solar cell calculated with the DA solver
 
 
  def this_dir_file(f):
- return os.path.join(os.path.split(__file__)[0], f)
+ from pathlib import Path
+ return str(Path(__file__).parent / "data" / f)
 
 
  # We need to build the solar cell layer by layer.

docs/source/Examples/example_RAT_of_ARC.rst

@@ -1,4 +1,4 @@
-Using the TMM solver to calculate the reflextion of a multilayered ARC
+Using the TMM solver to calculate the reflection of a multilayered ARC
 ======================================================================
 
 .. image:: RAT_of_ARC.png

docs/source/Examples/example_optics_comparison.rst

@@ -38,7 +38,7 @@ due to diffraction effects.
  from solcore.solar_cell_solver import solar_cell_solver, default_options
  from solcore.light_source import LightSource
  from solcore.constants import vacuum_permittivity
- from solcore.optics import RCWASolverError
+ from solcore.absorption_calculator import RCWASolverError
 
  # user options
  T = 298

docs/source/Examples/example_substrate.rst

@@ -33,7 +33,7 @@ Looking at the effect of substrate and the no_back_reflection option in the TMM
 
  # Thin solar cell, no substrate - will get significant absorption enhancement from reflection at the GaAs/air interface at the back
  # MUST specify no_back_reflection = False, so that Solcore does not automatically suppress reflections from the back
- # (currently, the default setting in solcore is to suppress reflections from the back, so no_back_reflection = True
+ # (currently, the default setting in solcore is to suppress reflections from the back, so no_back_reflection = True)
  solar_cell_solver(thin_GaAs, 'optics', user_options={'wavelength': wl, 'optics_method': 'TMM', 'no_back_reflection': False})
  z_pos = np.linspace(0, thin_GaAs.width, 201)
  profiles_thin = thin_GaAs[0].absorbed(z_pos)

docs/source/Examples/tutorial.rst

@@ -169,14 +169,6 @@ of the window and BSF layers, and (2) the missing layers are added
 outside the Junction object when creating the full solar cell in order
 to consider their optical properties (see below).
 
-**TRICK:** The TMM solver work best with "thin" layers therefore, if the
-results of optical calculations look strange, try dividing thick layers
-(> 2-3 µm) into thinner ones (~500 nm). The reason is that the waves
-propagating forwards and backwards, leading to interference are
-ultimately complex exponentials that increase (or decrease) quite fast
-away from the interfaces, resulting in a loss of numerical accuracy when
-they trying to interact far from the interfaces.
-
 The only tunnel junction of this solar cell will be defined according to
 the parametric model and we will assume it is made of GaInP layers, 40
 nm-thick in total, that will block part of the light reaching the bottom
@@ -246,6 +238,7 @@ code that defines the spectrum to use and lunch the calculation will be:
  solar_cell_solver(my_solar_cell, 'qe',
  user_options={'light_source': light_source, 'wavelength': wl, 'optics_method': 'TMM'})
 
+
 The calculation will proceed in several stages: (1) The structure is
 processed and discretized, (2) the problem is solved under equilibrium,
 (2) the problem is solved under short circuit conditions increasing in
@@ -256,17 +249,6 @@ densities at equilibrium (dashed line) and at short circuit (continuous
 line), as well as the EQE of the two junctions and the total absorption
 in the layers.
 
-.. code:: python
-
- from solcore.solar_cell_solver import solar_cell_solver
- from solcore.light_source import LightSource
-
- light_source = LightSource(source_type='standard', version='AM1.5g', x=wl,
- output_units='photon_flux_per_m', concentration=1)
-
- solar_cell_solver(my_solar_cell, 'qe',
- user_options={'light_source': light_source, 'wavelength': wl, 'optics_method': 'TMM'})
-
 .. figure:: qe.jpg
  :alt: Quantum efficiency
 

docs/source/Installation/Solcore_on_MacOSX.md

@@ -1,7 +1,7 @@
 Solcore on Mac OS X
 =====================
 
-Solcore has been heavely tested under Mac OS X, so there should be no problems. However, using NGSPICE requires some details, as shown below.
+Solcore has been heavily tested under Mac OS X, so there should be no problems. However, using NGSPICE requires some details, as shown below.
 
 Installing NGSpice on MacOSX
 ----------------------------

docs/source/Installation/Solcore_on_Windows.md

@@ -1,95 +1,90 @@
 Solcore on Windows 10
 =====================
-The Python part of Solcore, which is the majority, should work under Windows with no problems. However, we have found a lot 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, please follow the instructions below. 
+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
+from periodic structures (e.g. diffraction gratings, photonic crystals). Thus, if you do not need this functionality, you 
+can stick with Windows.
 
 Installing Solcore
 ------------------
-(thanks Phoebe!)
 
-After a lot of effort, we have Solcore fully up and running in Windows 10... more or less, using the Ubuntu shell that comes with Windows 10. To install Solcore there, follow this steps:
-
-All steps on fresh install of Ubuntu (using the Ubuntu terminal on
-Windows 10 distributed by Canonical Group, Ubuntu 16.04.3 LTS, Codename:
-xenial)
-
-- Install git if not done already
-- Install python 3.x if not already done
-- Install pip3 (for installing Python3 packages; you may need to update the package list first: sudo apt-get update)::
-
-```bash
-sudo apt install python3-pip
-```
-- You need LAPACK and BLAS libraries linked to the -llapack and -lblas library flags – these are used for scipy and S4. The developers of S4 recommend OpenBLAS (you can find installation instructions by Googling), but this also works and is simpler:
-
-```bash
-sudo apt-get install libblas-dev liblapack-dev
-```
-
-- Install matplotlib (and tk, otherwise get an error later):
-
-```bash
-pip3 install matplotlib
-sudo apt-get install python3-tk 
-```
-
-- Other dependencies install automatically & successfully when
- installing Solcore5... hopefully.
-
-- Now, we actually Install Solcore::
-
-```bash
-git clone https://github.com/dalonsoa/solcore5.git
-cd solcore5
-sudo python3 setup.py install
-```
+It is possible to run all the parts of Solcore from a Windows 10 environment without using a virtual machine or dual-booting a UNIX operating
+system (e.g. Ubuntu). This can be done by using the Windows Subsystem for Linux (WSL) which can be installed on Windows 10. 
+By itself,
+the WSL does not support graphical applications, but it is possible to use Python installed in the WSL from a development
+environment running in Windows (such as VSCode), including plotting capabilities. Step-by-step instructions for
+setting up the WSL and accessing it from VSCode are given [here](https://code.visualstudio.com/docs/remote/wsl-tutorial).
+Note that to be able to see plots generated during code execution you can right-click on the Python file you want to execute
+in VSCode and select 'Run Current File in Python Interactive window'. This has been tested on 64-bit Windows 10 using
+the Ubuntu20.04 version of the
+WSL (using [WSL 2](https://docs.microsoft.com/en-us/windows/wsl/install#upgrade-version-from-wsl-1-to-wsl-2)); both S4
+and the PDD install and run without issues.
+
+If you would like to use a different development environment, you will have to check if it supports accessing Python from
+the WSL from a Windows application; it
+is possible in [PyCharm](https://www.jetbrains.com/help/pycharm/using-wsl-as-a-remote-interpreter.html).
+
+However, depending on your preferences you may still want to use a virtual machine or dual boot your computer to run a 
+complete Linux operating system. Whichever option you choose, you should be able to install Solcore in your preferred way
+using the normal installation
+instructions; instructions for installing S4 on Ubuntu, if you want to use it, are given below.
 
 Installing S4
 -------------
 
-- The “make” command must be available:
+These are the steps for installing S4 in an Ubuntu WSL environment (through the WSL command line environment). These steps
+should be the same for any Ubuntu environment.
 
-```bash
-sudo apt install make
-```
+- The “make” and “git“ commands must be available:
 
-- You must use the fork of S4 at https://github.com/phoebe-p/S4; the
- main branch is not compatible with Python 3.x:
+ ```bash
+ sudo apt install make git
+ ```
+
+- You need LAPACK, BOOST, FFT and BLAS libraries to compile S4. The developers of S4 recommend OpenBLAS (you can find installation 
+ instructions by Googling), but this also works and is simpler:
+
+ ```bash
+ sudo apt install libopenblas-dev libfftw3-dev libsuitesparse-dev libboost-all-dev
+ ```
 
-```bash
-git clone https://github.com/phoebe-p/S4.git
-cd S4
-make S4_pyext
-```
+ (if you have any issues, more detailed installation instructions can be found [here](https://github.com/phoebe-p/S4).)
+- You must use the fork of S4 at [https://github.com/phoebe-p/S4](https://github.com/phoebe-p/S4), as the
+ main branch is not compatible with Python 3:
+
+ ```bash
+ git clone https://github.com/phoebe-p/S4.git
+ cd S4
+ make S4_pyext
+ ```
 
 Checking if everything works 
 --------------------------
 
 - To see if the PDD is working:
 
-```bash
-python3
->>> import solcore.solar_cell_solver
-```
+ ```bash
+ python3
+ >>> import solcore.solar_cell_solver
+ ```
 
 - Run tests:
 
-```bash
-sudo python3 setup.py test
-```
-
-This might result in an error saying that quantum mechanics failed because 5\ :sup:`th` decimal place of result doesn’t match. Simply, ignore it.
-
-- Other information:
- - gcc/g++/gfortran versions used here: gcc version 5.4.0 20160609 (Ubuntu 5.4.0-6ubuntu1~16.04.6)
-
- - If everything is working correctly, should be able to import
- solcore.solar_cell_solver without getting warnings about the RCWA
- solver or PDD.
+ ```bash
+ sudo python3 setup.py test
+ ```
 
- - Sometimes, an issue arises with the SOPRA database (and occasionally
- importing solar_cell_solver?) where the permissions are set such that
- you cannot access the database – running sudo python3, or sudo
-  [whatever python editor you’re using] fixes this.
+This might result in an error saying that quantum mechanics failed because the 5th decimal place of result doesn’t match. 
+You can simply ignore this error. If everything is working correctly, should be able to `import solcore.solar_cell_solver` 
+without getting warnings about the RCWA solver or PDD.
+
 
 Installing SMARTS Windows10/Ubuntu Shell 
 ----------------------------------------

docs/source/Installation/compilation.md

@@ -4,7 +4,7 @@ In order to use the Poisson-Drift-diffusion solver, it will be necessary to have
 
 ## Linux
 
-Most linux systems have a Fortran compiler already installed, typically part of GCC, the GNU compiler collection. If not, you will need to check how to install it for your particular linux distribution. 
+Most Linux systems have a Fortran compiler already installed, typically part of GCC, the GNU compiler collection. If not, you will need to check how to install it for your particular linux distribution. 
 
 ## Mac OS X
 
@@ -14,6 +14,10 @@ For Mac OS X we have used the *gfortran* compiler installed together with GCC us
 
 Other package managers like [MacPorts](https://www.macports.org) or [Fink](http://www.finkproject.org) might also work, but we have not tried. 
 
+There is currently a known issue involving the compilation of the PDD solver on new Macs with M1/ARM/Apple silicon chips. 
+The homebrew version of gfortran (installed above alongside gcc as indicated above) does not work. For a workaround please
+see [here](https://github.com/qpv-research-group/solcore5/issues/209).
+
 ## Windows
 
 To get a Fortran compiler properly working under Windows with F2Py, we have followed the [detailed instructions written by Michael Hirsch](https://www.scivision.co/f2py-running-fortran-code-in-python-on-windows/). Read Michael Hirsch's instructions in full for a complete picture, but the important bits are: