☰ TOC

How to run simulations

Workflow

The essential workflow to run simulations with Quokka3 consist of 3 separate steps:

1. Define your simulation input parameters in a settingsfile within a text-editor of your choice (Notepad++ is a good choice). Get a list of available parameters or information about a particular parameter via the settings lookup.
2. Start the simulation and manage cloud simulations using either the GUI or the command-line. For larger cloud simulations, the recommended way is to start the simulation, disconnect, and retrieve the results once finished.
3. Post-process the results via the GUI’s basic plotting functionality, or by processing the output files yourself.

The core of Quokka3 which performs the actual simulations, comes in two ways:

• a restricted free version, which is included as a standalone executable.
• the paid versions, which exclusively run as a cloud-service controlled via Quokka3-client, and consequently require internet connection.

The way of controlling simulations in Quokka3-client is (almost) identical regardless whether you use the included free version or the cloud-service. Only for using the cloud-service, one needs to have signed up for a user account.

Note that for the cloud, it sometimes might take up to a couple of minutes for the simulation to start. This has to do with automatic scaling of cloud-servers and is currently not entirely avoidable. The scaling algorithms are however monitored and optimized in such a way that only very rarely this delay should be significant compared to the overall simulation time. It should be a few minutes at maximum.

If a connected cloud-simulation finishes or a finished cloud-simulation is opened, the results are automatically downloaded and deleted from the cloud. Only some anonymous metadata like simulation time, memory usage etc., are kept for statistical and service-improvement purposes.

System requirements

Installation of Quokka3 is required both for free and paid-version usage, which should also be possible without admin rights. It is currently available for Windows 64bit only. As the included standalone free core executable allows only small simulations, and large simulations are exclusively performed in the cloud, Quokka3 doesn’t require highly performant computer hardware for simulations. It should work on any reasonable up-to-date Windows PC. A MAC version is in the making, but not yet released.

The 3D view functionality of the GUI requires OpenGL > 3.0. Rarely for old graphic card drivers the required “gpu_shader4 extension” is missing, which can potentially be fixed by updating the graphics card driver. If you suspect graphics problems of the GUI, you can try to enable software OpenGL rendering by placing the following file next to the Quokka3.exe: opengl32.dll

To use the paid versions, the computer must have internet connection to access the cloud service. Connection is made over standard https / http protocol on its default ports 443 / 80, making it indifferent to browsing websites. However, sometimes internet access for newly installed software is blocked by company firewall settings, in which case you should check your firewall / malware settings and add an exception. Quokka3 also supports the use of a proxy server.

Installation

First, download the current version of Quokka3, either the installer or extract the zip archive into a new folder of your choice. Quokka3 will install the following files

• config.ini: this file is created within your application data folder when first starting the software and contains configuration settings; you do normally not need to open that file yourself.
• Quokka3.exe: the main Quokka3 application, starts the GUI
• q3core.exe: a free core executable for performing local offline simulations; it is restricted in functionality, the full version can only be accessed via the cloud service
• Quokka3_cmd.exe: placed besides the main executable, allows simulation control via the command-line

GUI

The purpose of the GUI is to conveniently control simulations and provide some basic results plotting functionality. It is not for defining the actual simulation parameters, which is done in the settingsfile. The plotting functionality provides a quick way to inspect main results, but it is not scoped to be a powerful generic post-processor. If you want to plot the results in a particular way of your liking, you need to read the results data from the results files and create the plots with your own tools.

The GUI features a File, Options and Help menu at the top, and a bottom section with the current status of the GUI, the currently loaded settingsfile and resultsfile. The main area consists of 4 panels:

• Simulation Control: Let’s you start and cancel local or cloud simulations, go online, show a list of current cloud simulations, and some other simulations controls.
• Simulation Log: displays live output during a running simulation, or the log of a finished simulation when downloaded from the cloud.
• 3D View: displays the geometric features and numerical 3D mesh of the last loaded settingsfile or resultsfile in a mouse-interactive view. Right-clicking on any item in the tree list will give some options to toggle visibility and highlighting that geometric item. You can double-click in the 3D view area to get a full-screen view.
• Plots: After a finished simulation, or after opening a resultsfile, you can create various kinds of plots in this panel. First select a results group, and then proceed downwards with data selection (an exclamation mark “!” means you have to select data by clicking on that button), until the “New” or “Add” button let’s you create a new plot or append the data to the current plot. Clicking “Modify” let’s you change the current plot, e.g. axis limits and linear / log scale.

File menu

In the file menu you can open a settingsfile or resultsfile.

The “Export” function allows you to:

• Export a generic settingsfile: this is useful if your settingsfile is created in a simplified syntax and you want to have the exact same settings in the generic syntax in order to make some modifications not possible within the simplified syntax.
• Export 3D view: exports the current 3D view with various image and 3D formats available.
• Export current plot: let’s you export the current plot’s data as a csv file, or as various image formats.

Options menu

Via the Options menu the cloud settings are accessible, which are required to enter if you want to access the full version via the cloud-service. Enter the username and password as provided during the licensing.

If your computer uses a proxy server to connect to the internet, then active “use proxy” and enter the server and port in the format “server:port” in the proxy address field.

The default connection to the cloud-server “cloud.quokka3.com” is done via a SSL secured connection on port 443, which is the typical way for end-to-end encrypted secure internet data transfer. It is also possible to connect to the cloud-server without secure connection on port 80, which may be useful for debugging purposes, or if encrypted internet connection is not strictly required.

When checking “remember password”, Quokka3 securely stores the password in the Windows Credentials store on your local computer, so you don’t need to re-enter it everytime you connect to the cloud.

Help menu

In the help menu you find the “settings lookup”, which let’s you list all parameters available for a settingsfile. First select a syntax for which you’d like to lookup a settings parameter. You will then already see a list of all available settings groups within that syntax. You can then enter any group, subgroup, or parameter in the text field, or copy-paste it from a settingsfile. After pressing “Enter” you will get a description and other information like dependencies which need to be fullfilled in order for that parameter to be applicable.

Simulation Control

Here the simulation is controlled, i.e. you can essentially start the actual simulation. If you have signed up for a user account you can connect to the cloud-service to access the full version, which will also enable parallel mode, the option to disconnect a running cloud simulation and the possibility for managing cloud usage as an admin user. You may disconnect a running simulation and start more simulations simultaneously until the license limits or your personal limits for CPU, RAM and CPU-hours usage have been reached. Disconnecting a simulation does not interrupt the simulation. It will then be listed in the lower box with the current status while you are only, and you can reconnect anytime by right-clicking the simulation. You can also abort and delete simulations in the cloud by right-clicking and selecting the corresponding option.

You can select a different solution type to override the setting in the settingsfile, to quickly simulate a variety of characteristics once your device properties are defined. If you enable the “append solution type to resultsfile name”, the name of the resultsfile will contain the solution type, which is useful to not overwrite results of the same settings just with a different solution type.

Checking “force storing spatial and map results” is identical to setting SaveSpatial=1; and SaveMaps=1 in the settingsfile. It forces Quokka3 to store spatial results in the resultsfile. If not checked, the spatial data will not be stored for larger simulations to save on filesize.

It is good practice to always check geometry before starting simulations. This is a very quick sanity check, and even if connected to the cloud uses only the local executable for fast performance and robustness. Note that if you have a sweep defined, “check geometry” will disregard it. “check geometry” will run a simulation using the “meshing only” solution type and save the results in a filename including “meshing only”.

Cloud management

When you click the “manage” button as a license admin, you will see a list of users on that license. You can then manage the users by setting individual limits for CPUs, RAM and CPU-hours. You can set a new password in case of a forgotten password. And you are also able to cancel all simulations of a user, e.g. if a user is accidentally using up all CPUs or RAM.

Note that the actual usernames are not shown in the list, as they are only stored encrypted in the cloud for data security. You rather see the “nicknames” of the users, which you are free to set to whatever you like in order to identify the users.

The addition of new users or removal of existing users can currently not be performed by the license admin. Please get in contact if you wish to add or remove user accounts on your license.

Updates

The GUI checks for updates each time you connect to the cloud. A popup window will appear if an update is available, with the options to update now or later. Updating works completely automated. A self-extracting archive (.exe) is executed during the update process, and you might get a respective warning.

Updating is strongly recommended as otherwise incompatibilities with the updated cloud-service can not be excluded.

Command-line

For scripted simulation control a command-line interface is provided via “Quokka3_cmd.exe”. The basic format to use it is

>Quokka3_cmd.exe [COMMAND] [PARAM1] [PARAM2]

The return code is -1 on error, and unless otherwise stated 0 for success. Only the command START_LOCAL uses the local free version, all other commands control cloud simulations. They require correct client settings and the password to be stored.

START_LOCAL

Starts a local simulation, i.e. using the free Quokka3-core executable. PARAM1 is the settingsfile, PARAM2 is not used. Example:

>Quokka3_cmd.exe START_LOCAL "C:\my folder with spaces\mysettingsfile.m"

START_WAIT

Starts a cloud simulation, continuously displays the log, downloads results and deletes the simulation from the cloud. PARAM1 is the settingsfile, PARAM2 is the number of cores to be used. Example:

>Quokka3_cmd.exe START_WAIT "C:\my folder with spaces\mysettingsfile.m" 2

START_DISCONNECT

Starts a cloud simulation and immediately returns. PARAM1 is the settingsfile, PARAM2 is the number of cores to be used. The last output message is the SIMULATION ID, which is required for the GET_LOG and DOWNLOAD_RESULTS commands. Example:

>Quokka3_cmd.exe START_DISCONNECT "C:\my folder with spaces\mysettingsfile.m" 2

GET_LOG

Retrieves and prints the log of a cloud simulation. Returns 0 if the simulation is finished, and 1 if it is still running. PARAM1 is the SIMULATION ID, PARAM2 is not used. Example:

>Quokka3_cmd.exe GET_LOG 1495811542680

DOWNLOAD_RESULTS

Downloads results of a finished cloud simulation and deletes it from the cloud. PARAM1 is the SIMULATION ID, PARAM2 is not used. Example:

>Quokka3_cmd.exe DOWNLOAD_RESULTS 1495811542680

Settingsfile

Structure

All input parameters for the device properties and its characteristics to be simulated are defined in a settingsfile. It is a plain ASCII text file which can be edited by any text editor of your choice. While any extension is supported (e.g. .txt), it is recommended to use .m as the extension. It is noted however that the settingsfile is NOT interpreted as a Matlab-script, in particular no variables or mathematical expressions are supported. The *.m extension is solely useful to enable syntax highlighting in text-editors (e.g. Notepad++), as the settings syntax is derived from the Matlab syntax (mainly commenting via “%” and vector definition).

The settings consist of a list of assignments in the following exemplary form:

group.subgroup.parameter = value [unit]; % comment

There are four different types of values (no other types like variables or expressions are supported):

• switch: to enable or disable something by setting it to 1 or 0 respectively
• scalar: a single numeric value excluding any unit, which can be set in common formats (e.g. 110, 1.1e2 or 1.1E+02); you can add a unit, e.g. 15 fA/cm2, otherwise the default unit is used; for available units of a particular parameter check the settings lookup
• string or option: a string value needs to be given in ‘single quotes’
• vector: a series of scalar values which can be defined in various ways, also with unit support

Some settings require the input of two-column tabulated (XY) data points, e.g. for the generation profile. There is a common way to define such XY input data, including via loading it from a file.

Quokka3 supports various syntaxes for providing a generic way of defining the simulation setup ([generic syntax][GS]), as well as simplified ways for various common simulation tasks (simplified syntaxes). With the considerably large functionality of Quokka3, the [generic syntax][GS] unavoidably results in longish parameter names from nested groups. For an easier start simplified syntaxes are recommended, mainly simplifying geometry definitions, which as a compromise address only a subset of Quokka3 functionality.

The settings (except the high level settings) are organized into various levels of groups separated by a dot. In the following tables, the parameters need to be preceded by the respective name of the group. Default settings are marked with an Asterisk* and are not required to be given.

To find an overview of available settings parameters, as well as a description, please check the settings lookup of the GUI.

High level settings

parameter	(recommended) value range	description
SaveSpatial	1 / 0	forces to save / not save spatial results; only applicable if the [solution type][ST] has a unique operating point; Quokka3 decides based on mesh size etc. if not given
SaveMaps	1 / 0	forces to save / not save map results; only applicable if the [solution type][ST] has a unique operating point; Quokka3 decides based on mesh size etc. if not given
DisplayPETSCResiduals	1 / 0*	enables / disables printing of PETSC residuals (useful for checking convergence)
CoordinateOutputUnit	‘m’, ‘cm’*, ‘mm’, ‘um’, ‘nm’	sets the unit of coordinates in results file
Syntax	[‘generic’][GS], ‘front and rear contact unit cell’, ‘1D detailed homojunction cell’, ‘near-surface skin’	What syntax to use: ‘generic’ for full functionality or simplified others for specific scenarios

Sweep

A sweep varies input parameters for a series of defined values. It supports two independent sweep groups A and B, within each multiple parameters can be varied at the same time. Within each group, the number of sweep values must be equal for all parameters. That means that (up to) a 2-dimensional sweep can be defined, where each dimension can consist of multiple simultaneously varied parameters. If a higher dimensional sweep it desired it is up to the user to linearize it into a 2- or 1-dimensional sweep.

There are some advantages of doing the sweep within Quokka3:

• gives a single results file summarizing all sweep results
• plotting functionality of GUI has the capability of quickly plotting main results as a function of the sweep parameters
• can be run in parallel mode to solve sweep points simultaneously
• Performance is better in certain scenarios, as Quokka3 can re-use some results from previous sweep-points for a faster simulation

Sweep settings group:

parameter	(recommended) value range	description
.Enable	1 / 0	enables / disables the sweep functionality
.NGroups	1 / 2	number if independent sweep groups; 1 means group A only, 2 means group A and B
.GroupA(ia).Parameter	‘parameter name’	can be any switch, scalar, string or option parameter, e.g. it is also possible to sweep filenames; multiple, consecutively indexed parameters can be defined
.GroupA(ia).Values	vector	vector of values; the same unit as for the respective parameter applied; all vector values within a group must have the same length
.GroupB(ib).Parameter	‘parameter name’	same as for GroupA
.GroupB(ib).Values	vector	same as for GroupB

As an example, the sweep settings

Sweep.Enable = 1; % enable sweep
Sweep.NGroups = 2;
Sweep.GroupA(1).Parameter = 'SkinFeature(1).Lumped.Electrical.Rsheet';
Sweep.GroupA(1).Values = [70 100 150];
Sweep.GroupA(2).Parameter = 'SkinFeature(1).Lumped.Electrical.J0'; % dependent parameter: higher Rsheet means lower J0
Sweep.GroupA(2).Values = [150 100 70]*1e-15;
Sweep.GroupB(1).Parameter = 'Bulk.Electrical.Recombination.LifetimeCurve.File'; % independent parameter
Sweep.GroupB(1).Values = ['file_1.csv' 'file_2.csv'];

will simulate the following 6 sweep points (shown in linearized form):

#	ia	ib	Rsheet	J0	File
1	1	1	70	150e-15	‘file_1.csv’
2	1	2	70	150e-15	‘file_2.csv’
3	2	1	100	100e-15	‘file_1.csv’
4	2	2	100	100e-15	‘file_2.csv’
5	3	1	150	70e-15	‘file_1.csv’
6	3	2	150	70e-15	‘file_2.csv’

XY input

XY-input settings group:

parameter	(recommended) value range	description
.Type	‘const’, ‘XY’, ‘file’	how to define XY values; ‘const’: constant Y value for any X value; ‘XY’: definition of X vector and Y vector; ‘file’ read XY values from a 2-column ASCII file or from a hdf5 file
.Const		constant Y value; unit as given in the parameter description
.X	vector	vector of X values; unit as given in the parameter description
.Y	vector	vector of Y values; unit as given in the parameter description
.File	‘filename’	name of file to be imported; must be either .csv or .txt for ASCII file, or .h5 for hdf5 file
.DataGroup	‘groupname’	name of group where XY data is located; expects datasets at /groupname/X and /groupname/Y; only for hdf5 file input

For ASCII file input, Quokka3 expects a 2-column file, first column X values and second column Y values. Most common delimiters are supported, and a single header row may be present. Commas as decimal marks are NOT supported (yet).

Vector input

There are 4 different ways to define vector values:

1. list of values in square brackets separated by spaces or commas (Matlab-style): [v1 v2 ... vn]

Example:

vecparam = [10 30 50 70 90 110];

2. first value, increment and last value separated by ‘:’ (Matlab-style): [v1:deltav:vn]

Example:

vecparam = [10:20:110]; % gives same vector as example above

3. ‘lin’ followed by a vector of first value, last value and number of values: lin[v1,vn,n]

Example:

vecparam = lin[10,110,6]; % gives same vector as example above

4. the syntax above can be alternatively preceded by ‘log’ to produce a logarithmically spaced vector instead: log[v1,vn,n]

Example:

vecparam = log[10,110,6]; % still starts at 10 and ends at 110, but the 6 points are spaced logarithmically

Any vector can be scaled by multiplying it with a number at the end.

Example:

vecparam = [1:2:11]*1e1; % gives the same vector as examples 1. - 3.

Any vector can also have a unit, for a available units see the settings lookup for the particular settings parameter.

Example:

vecparam = [1:2:11]*1e1 fA/cm2; % gives the same vector as examples 1. - 3. in units of fA/cm2 instead of default units

Generic syntax

The so-called “generic syntax” is the fundamental syntax of Quokka3 which gives access to all available functionalities without restrictions. In particular the geometry settings of the skin, contact, metal and pad features need to be defined manually based on the coordinates and sizes of the features. This is greatly simplified within the simplified syntaxes, which are therefore the recommended starting point when beginning to use Quokka3, in particular when coming from free Quokka v2.

When using the generic syntax, the following rules must be followed, for simplicity assuming features in the XY-plane in the following:

• The domain corner is defined at X=0 and Y=0 (and Z=0), and extends in positive directions. That also means that the rear side is placed at Z=0, also in the simplified syntaxes, which is different to many other solar cell simulations tools.
• For each skin, contact, metal or pad “feature”, if not defined full-area, the “Position” must be given, which defines the center (not corner) of this feature. The shape is recommended to be rectangular due to being best compatible with the rectangular numerical mesh of Quokka3, however also a circular shape is supported, resulting in usually much higher required mesh sizes.
• Features may well extend the domain. This does not influence the simulation, as everything outside of the domain bounds is not included in the numerical mesh, and thereby not existent.

Below image shows the rear side of the ANU IBC example defined via the generic syntax, contained in the 2014 unit cells example.

Simplified syntaxes

front and rear contact unit cell

The scope of this syntax is to define common unit cell solution domains for cell designs having contacts at the front and rear side with a typical H-pattern or full-area metallization. It greatly simplifies geometry definition by not having to figure out and define every position and size of the geometric features. It is an easy starting point into Quokka3, and the recommended syntax for all common non-full-area silicon solar cell simulations.

This syntax supports a ‘busbar enhanced’ unit cell type, where an H-pattern metallization can be set and half of a busbar and half of a finger length is included in the domain. In contrast to the standard unit cells, the ‘busbar enhanced’ one can correctly account for localized shading and recombination of the busbars, and the distributed finger resistance opposed to a lumped series resistance value. If a H-pattern metallization is set both at the front and rear side, bifacial cell designs can thoroughly be modeled.

Notably one can set a different contact pitch at the front and rear side, which must otherwise be closely related in common unit-cell simulation, usually being restricted to equal, half or double. Quokka3 finds the least-common multiplier of the two pitches, and this way creates the “true” symmetry element for any pitch combination. However, the user should take care to use sensible numbers, to prevent a very large mesh and simulation time. But there is no limit on practically realizable pitch combinations in Quokka3, as at the far end one can define a full cell with the actual geometry (using the generic syntax).

Conduction types and polarities (n-type or p-type) of all features are ignored, but defined globally via ‘FrontMetalPolarity’ and ‘RearMetalPolarity’, which must be opposite.

front and rear contact full cell

This syntax is similar to the ‘front and rear contact unit cell’ in that it defines a both-sides contacted solar cell with H-patterned or full-area metallization at the front and rear. It differs in that it defines the geometry based on a full-cell view, meaning cell size, busbar and finger numbers, instead of the respective pitches. Most notably, it accounts for edge effects, featuring the optional inclusion of a redundant-line. It further supports a shingle cell layout.

The syntax allows different solution domains to represent the full cell by the ‘FullCellDomainType’ parameter:

• ‘full’ builds the 3D geometry of the entire cell
• ‘half-symmetry’ and ‘quarter-symmetry’ builds the respective symmetry element only
• ‘multi-domain’, see below

multi-domain approach

The multi-domain approach automatically constructs multiple different solution domains comprising an inner domain and one or two edge domains (for a shingle layout there is only one edge domain). By the sole assumption that the busbars have a constant potential, which is inherit to this simplified syntax anyway, the full-cell characteristics including edge effects can be accurately simulated with a fraction of the computational demand. This in particular enables to accurately simulate full-cell characteristics of more complex cell designs, e.g. featuring dot / dashed rear-contacts, as those would result in prohibitively large meshes for the other full-cell domain types.

An additional benefit is that by comparing the final result from the inner and edge domains the edge losses of the full cell design are directly quantified, whereas the other domain types would require an additional simulation (e.g. a busbar-enhanced unit-cell simulation) as an edge-loss-free reference point.

1D detailed homojunction cell

The ‘1D detailed homojunction cell’ syntax defines 1D semiconductor device consisting of a homogenous material, i.e. having skins of ‘near-surface’ type at the front and the rear. NOT YET IMPLEMENTED IN VERSION 2.

near-surface skin

With the ‘near-surface skin’ syntax one can define a ‘semiconductor skin’ domain which represents a near-surface region. It is useful for example to simulate the (injection dependent) \(J_{0,skin}\) of a highly doped or passivated silicon surface. NOT YET IMPLEMENTED IN VERSION 2.

Results files

Simulation results are output in two different files:

• A HDF5 (.h5) file, containing all rendered results. HDF5 is an open-source file format specifically developed to store large datasets of different types into a group-structure. Data can be browsed, read and further processed by many scientific software tools (e.g. Matlab, Mathematica, Python, …). It also contains metadata, e.g. sweep parameter names, units, used version, etc.
• An Excel (.xlsx) file, containing a subset of the results and can be conveniently opened in Excel.

What kind of results are rendered by Quokka3 is dependent on the simulation setup, in particular the solution type (and whether it contains a unique operating point), and the sweep settings. There are 4 different types of results: Scalar, Curves, Maps and Spatial results. They are stored in Groups with the respective name in the HDF5 file, and in separate sheets for the Excel file.

• Scalar: a single numeric value (e.g. Voc). If a sweep is defined, this will be an array of values according to the sweep dimensions. For a two-dimensional sweep (i.e. using GroupA and GroupB sweep parameters), Scalars are stored as 2D arrays in the hdf5 file, which easily allows for e.g. contour plots. In the Excel file the results from a 2D sweep are linearized.
• Curves: curves are rendered only for ‘curve’-solution types. For a sweep, the set of curves for each sweep point is stored in a separate subgroup named ‘/Sweep(ia,ib)/’ in the HDF5 file.
• Maps: The luminescence intensity and some sheet properties of the boundaries are stored as maps. Maps are 2D arrays in the XY plane, and are only stored in the HDF5 file. For a sweep, equivalent subgroups as for Curves are created. Maps may not be stored by default, but can be forced to be stored.
• Spatial: In the HDF5 file spatial data is always stored as 3D arrays, regardless of the dimensions of the solution domain. Note that the order of the dimensions is Z, X, Y. It also contains vectors for the element center and face positions in each coordinate direction. Some spatial results, e.g. current densities, are defined at element face positions rather than centers, and have consequently one more data point in the respective coordinate direction. In the Excel file only 1D spatial data is stored. For a sweep, equivalent subgroups as for Curves are created. Spatial data may not be stored by default, but can be forced to be stored.