Add QElmerRenderer (#882)

README_Gmsh_Elmer.md

@@ -0,0 +1,85 @@
+# Softwares to Install for Open-source simulation toolchain for Qiskit Metal
+## Gmsh
+- This is a design rendering and meshing software that we will be using to render our design and then divide it into fine elements (called a `mesh`), in order to solve the necessary differential equations (PDE's of Maxwell's Electromagnetic Laws). This is completely integrated with Qiskit Metal and is semi-automated.
+- This will be automatically installed when you make a new `venv` environment and install qiskit metal using the instructions given above (except in Apple Silicon Macs, see the Note below).
+
+### Test if Gmsh is properly installed
+- Run the following in your terminal. A blank Gmsh window should open up. If it does, then hurray, you did it! 😄
+```bash
+$ gmsh
+```
+
+- Open a python REPL in your terminal and type `import gmsh` in the REPL. If `gmsh` gets imported without any errors, then it's installed properly with python.
+```python
+$ python
+...
+...
+>>> import gmsh   # No Error
+>>>
+```
+
+**NOTE:**
+- On Apple Silicon Macs (with M1 and M2-series chips), installing Gmsh using `pip install gmsh` might not work for importing the package using python. Therefore, to successfully install Gmsh, and point it to the `gmsh` installed using `pip`, you need to install `gmsh` binary through [Homebrew](https://brew.sh/) as follows:
+```bash
+$ brew install gmsh
+```
+- Restart your terminal, activate the environment, and check if you're able to do `import gmsh` in a python REPL or a scratch jupyter notebook. If the import is successful, then congratulations, you've installed Gmsh successfully!
+
+- **Note:** If the above steps still gives error in importing gmsh using `import gmsh` in your python environment, refer [this issue](https://gitlab.onelab.info/gmsh/gmsh/-/issues/1705), on the Gmsh GitLab repository, for more information. Also please feel free to contact us through the Qiskit Slack workspace on the `#metal` channel.
+
+## ElmerFEM
+- Congratulations on making it until here! Now we'll see how to install ElmerFEM.
+- ElmerFEM is a Finite Element Method (FEM) solver that we'll be using to take the mesh generated by Gmsh, and the solve the Maxwell's equations on top of our meshed design. Right now, Qiskit Metal only supports capacitance-type simulations (Poisson equaiton solver provided by `StatElecSolver`) with ElmerFEM, so only LOM 2.0 analysis can be performed for tuning the qubits using the results obtained from ElmerFEM in the form of a Maxwell Capacitance matrix.
+- ElmerFEM doesn't come as a python library and has different installation options on your operating system.
+- Please follow the official guide provided by Elmer Foundation CSC, [here](https://github.com/ElmerCSC/elmerfem#elmer-fem)
+
+**NOTE:** For MacOS, please consider building the software from source rather than using Homebrew on Mac, as the homebrew install isn't very consistent and may cause issues in the future.
+
+### After you complete your installation
+- Add your installation path directory to your system's `PATH` environment variable (you can skip this on Windows and MacOS, as it is automatically done on those OS platforms during the installation steps).
+- Restart your terminal.
+- Check if ElmerFEM is installed successfully by checking installation for `ElmerGrid` and `ElmerSolver`.
+- For testing ElmerGrid, type `ElmerGrid` in your terminal and if the PATH variable is set correctly, it should print a long output text. Check if you see the following at the end of the text:
+```bash
+$ ElmerGrid
+Starting program Elmergrid
+****************** Elmergrid ************************
+This program can create simple 2D structured meshes consisting of
+linear, quadratic or cubic rectangles or triangles. The meshes may
+also be extruded and revolved to create 3D forms. In addition many
+mesh formats may be imported into Elmer software. Some options have
+not been properly tested. Contact the author if you face problems.
+
+...
+...
+...
+
+Thank you for using Elmergrid!
+Send bug reports and feature wishes to elmeradm@csc.fi
+```
+
+- For testing ElmerSolver, type `ElmerSolver` in your terminal and if the PATH variable is set correctly, it should print a long output text. Check if you see the following:
+
+```bash
+$ ElmerSolver
+ELMER SOLVER (v 9.0) STARTED AT: 2023/01/11 09:42:44
+ParCommInit:  Initialize #PEs:            1
+MAIN: OMP_NUM_THREADS not set. Using only 1 thread per task.
+MAIN:
+MAIN: =============================================================
+MAIN: ElmerSolver finite element software, Welcome!
+MAIN: This program is free software licensed under (L)GPL
+MAIN: Copyright 1st April 1995 - , CSC - IT Center for Science Ltd.
+MAIN: Webpage http://www.csc.fi/elmer, Email elmeradm@csc.fi
+MAIN: Version: 9.0 (Rev: 02f61d697, Compiled: 2022-11-08)
+MAIN:  Running one task without MPI parallelization.
+MAIN:  Running with just one thread per task.
+MAIN: =============================================================
+ERROR:: ElmerSolver: Unable to find ELMERSOLVER_STARTINFO, can not execute.
+Note: The following floating-point exceptions are signalling: IEEE_OVERFLOW_FLAG
+STOP 1
+```
+
+If you see the above lines in the text in your terminal, then CONGRATULATIONS!!! You've successfully installed everything needed for using Gmsh and ElmerFEM with Qiskit Metal! 😄
+
+**NOTE:** If you face issues at any of the steps above, feel free to contact us on #metal channel on Qiskit slack!!

README_developers.md

@@ -115,6 +115,12 @@ Here are some things to consider when setting up a development environment:
 * Library errors when activating conda environments, or initializing jupyter notebook/lab, might indicate a conflict between python libraries in the base and sub environments. Go ahead and manually delete the library from the base environment `site-packages` folder, shown in the error message. You might need to reinstall them in the sub environment, or create a new one.
 * If Jupyter notebook has trouble finding a dll for a package that works in the new environment outside of Jupyter, then try opening Jupyter notebook from the new environment instead of from `base`
 
+### Installing other dependencies for Open-source Renderers (Gmsh and ElmerFEM)
+
+If you want to use the recently added open-source renderers for [Gmsh](./qiskit_metal/renderers/renderer_gmsh) and [ElmerFEM](./qiskit_metal/renderers/renderer_elmer) for simulation of your design, please make sure that both of them have been installed successfully in your system before running Qiskit Metal. On Windows, Linux, and MacOS (with x86_64 architecture CPUs), Gmsh will be installed automatically using the `environment.yml` file during the conda installation step above. For more detailed steps to install ElmerFEM, please refer to [this](./README_Gmsh_Elmer.md) document.
+
+**NOTE:** We would like to give a disclaimer for users on Apple silicon Macs (M1 and M2-series). Currently, Qiskit Metal uses PySide2 which is not natively supported on the ARM architecture. This will lead to error in instantiating the `MetalGUI` as of now. However, if you still want to use Qiskit Metal without the GUI, the process for installing Gmsh software is a bit different and can be found in [this](./README_Gmsh_Elmer.md) document.
+
 # Other Common Issues
 
 For other common installation issues, please refer to the [FAQ](https://qiskit.org/documentation/metal/faq.html)
@@ -149,4 +155,4 @@ Go to directory with qiskit-metal/.style.yapf  file and run the above command to
 rm /hooks/pre-commit
 ```
 
-If you need to uninstall the precommit hook, go to the root of the project and run the above command.
+If you need to uninstall the precommit hook, go to the root of the project and run the above command.

environment.yml

@@ -21,6 +21,7 @@ dependencies:
   - shapely==2.0.1
   - jupyter==1.0.0
   - scqubits==3.1.0
+  - pyyaml==6.0
   - pip==23.0
   - pip:
       - pyaedt==0.6.46

qiskit_metal/config.py

@@ -30,6 +30,10 @@
              class_name='QQ3DRenderer'),
     gds=Dict(path_name='qiskit_metal.renderers.renderer_gds.gds_renderer',
              class_name='QGDSRenderer'),
+    gmsh=Dict(path_name='qiskit_metal.renderers.renderer_gmsh.gmsh_renderer',
+              class_name='QGmshRenderer'),
+    elmer=Dict(path_name='qiskit_metal.renderers.renderer_elmer.elmer_renderer',
+               class_name='QElmerRenderer'),
 )
 """
 Define the renderes to load. Just provide the module names here.

qiskit_metal/renderers/__init__.py

@@ -107,4 +107,4 @@
     from .renderer_ansys.q3d_renderer import QQ3DRenderer
 
     from .renderer_gmsh.gmsh_utils import Vec3DArray
-    from .renderer_gmsh.gmsh_renderer import QGmshRenderer
+    from .renderer_gmsh.gmsh_renderer import QGmshRenderer

qiskit_metal/renderers/renderer_elmer/__init__.py

@@ -0,0 +1,14 @@
+# -*- coding: utf-8 -*-
+
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2017, 2022.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+""" ElmerFEM QRenderer """

qiskit_metal/renderers/renderer_elmer/elmer_configs.py

@@ -0,0 +1,74 @@
+"""Configuration settings used by ElemerFEM. For details, please refer
+to the ElmerFEM documentation http://www.elmerfem.org/blog/documentation/
+"""
+
+# Dictionary containing a database of materials and their properties to be
+# assigned to an ElmerFEM model.
+materials = dict(
+    vacuum={
+        "Electric Conductivity": 0.0,
+        "Relative Permittivity": 1,
+    },
+    silicon={
+        "Relative Permittivity": 11.45,
+    },
+)
+
+# Dictionary containing valid ElmerFEM simulation types and dimensions with
+# their correspoding settings (e.g. steady state 3D, transient 2D, etc.).
+simulations = dict(
+    steady_3D={
+        "Max Output Level": 5,
+        "Coordinate System": "Cartesian",
+        "Coordinate Mapping(3)": "1 2 3",
+        "Simulation Type": "Steady state",
+        "Steady State Max Iterations": 1,
+        "Output Intervals": 1,
+        "Timestepping Method": "BDF",
+        "BDF Order": 1,
+        "Solver Input File": "case.sif",
+        "Post File": "case.ep",
+        "Output File": "case.result",
+    })
+
+# Dictionary containing valid ElmerFEM solvers and their correspoding
+# settings (e.g. StatElecSolver, ResultOutputSolve, etc.).
+solvers = dict(
+    capacitance={
+        "Equation": "Electrostatics",
+        "Calculate Electric Field": True,
+        "Calculate Capacitance Matrix": True,
+        "Capacitance Matrix Filename": "capacitance.txt",
+        "Procedure": '"StatElecSolve" "StatElecSolver"',
+        "Variable": "Potential",
+        "Calculate Electric Energy": True,
+        "Exec Solver": "Always",
+        "Stabilize": True,
+        "Bubbles": False,
+        "Lumped Mass Matrix": False,
+        "Optimize Bandwidth": True,
+        "Steady State Convergence Tolerance": 1.0e-5,
+        "Nonlinear System Convergence Tolerance": 1.0e-7,
+        "Nonlinear System Max Iterations": 20,
+        "Nonlinear System Newton After Iterations": 3,
+        "Nonlinear System Newton After Tolerance": 1.0e-3,
+        "Nonlinear System Relaxation Factor": 1,
+        "Linear System Solver": "Iterative",
+        "Linear System Iterative Method": "BiCGStab",
+        "Linear System Max Iterations": 500,
+        "Linear System Convergence Tolerance": 1.0e-10,
+        "BiCGstabl polynomial degree": 2,
+        "Linear System Preconditioning": "ILU0",
+        "Linear System ILUT Tolerance": 1.0e-3,
+        "Linear System Abort Not Converged": False,
+        "Linear System Residual Output": 10,
+        "Linear System Precondition Recompute": 1,
+    },
+    postprocessing_gmsh={
+        "Exec Solver": "Always",
+        "Equation": "Result Output",
+        "Procedure": '"ResultOutputSolve" "ResultOutputSolver"',
+        "Output File Name": '"case"',
+        "Output Format": "gmsh",
+    },
+)