The oghma file format

1. What is JSON?

OghmaNano stores its simulation information in a JSON file. JSON (JavaScript Object Notation) is a very simple, text-based format for storing and transmitting structured data. It is widely used in scientific software because it is both human-readable and machine-parsable. You can see general examples of JSON structures at https://json.org/example.html.

To illustrate how JSON works, below is a simple example. A JSON file is built from sections that start and end with curly brackets { }. Each section contains tokens, or labels, such as "color_of_dog", "dog_age", or "dogs_toys". These tokens must always be written in double quotes, and they are followed by a colon : and then the associated data value. Text values are placed in double quotes, while numbers such as integers or decimals are written without quotes. In OghmaNano, boolean-like values are stored as the strings "true" or "false". For the file to be valid, all opening and closing brackets must line up correctly. Items within a section are separated by commas, except for the final item, which does not end with a comma. ??.

{
  "color_of_dog": "brown",
  "dog_age": 5,
  "dogs_toys":
  {
    "rabbit": "true",
    "stick": "false"
  }
}

OghmaNano uses the same JSON principles to store all of its simulation data. This information is contained in a file named sim.json, which contains all of the device parameters, simulation settings, and output configuration. Each simulation will have it's own sim.json file. While you can open this file in any text editor, it is often easier to use a dedicated JSON viewer as it will format the data in an easy to read tree structure. Firefox has a nice built in json viewer. An example of a sim.json file viewed in Firefox is shown in below in ??

One final point: although sim.json is the key configuration file, it is not always stored on its own. Instead, OghmaNano often packages it inside a sim.oghma file, which is just a standard ZIP archive - this is to save space. If you rename sim.oghma to sim.zip, you can open it with Windows Explorer or any zip viewer and extract sim.json. If you place a copy of sim.json in the same simulation directory and rename the archive back to sim.oghma, OghmaNano will ignore the archived version of sim.json and use your plain text sim.json file instead. This feature is extremely useful for automation, since you can directly edit sim.json using any programming language without needing to manipulate zip files.

2. The OghmaNano file format

OghmaNano applies exactly these principles in its simulation configuration file, named sim.json. This file contains everything needed to describe a device structure, define the simulations to be run, and configure the solvers. Each simulation directory will include its own sim.json. Although you can open this file in any text editor, it is often more convenient to use a JSON viewer such as Firefox, which automatically presents the data in a formatted tree view.

At the highest level, sim.json is organised into a small number of top-level sections. These sections then branch into detailed subsections, such as JV sweeps, EQE runs, or device layer definitions. The main top-level sections present in the current format are summarised in the table below: ??.

3. Quirks of the OghmaNano json format

• The OghmaNano json file does not support standard json lists e.g. ["Red", "Green", "Blue"]. If there is a list of items, it is defined by firstly declaring the variable segments, with the number of items in the list so for example "segments",0 . Each item in the list is then stored under, "segment0", "segment1" etc... This format enables OghmaNano to allocate the memory for reading in the structures before doing the reading. This can be seen in figure 14.1 where there is a list with 1 segment.

• Many items in the json file will be given an ID number which is a 16 digit hex code, this can be used to uniquely reference the item. An ID number can also be seen in figure 14.1. These ID numbers are generated at random but every ID number must be unique. ID numbers enable objects for example epitaxy layers to be identified uniquely even if they have the same name.

4. Encoding

The .json files read/written by OghmaNano are always stored in UTF-8 format. OghmaNano can not handle UTF-16 or any other text encoding standards. Nowadays windows notepad and most other apps default to UTF-8, so if you don’t know what these text storage formats are it probably does not matter. This will only rear it’s head if you start programmatically generating .oghma files in a language such as C++ and are using a language such as Chinese or Russian with non Latin characters in it’s alphabet.

5. Forwards/backwards compatability of the file format

Significant effort is made to make sure new versions of OghmaNano can read files generated in older versions. However, older versions of OghmaNano may not be able to read files generated on newer versions. Every time the user opens a sim.oghma file using the GUI the file format is checked and if it differs to that being used in the current version the file is updated and written back to disk. If you are using OghmaNano in a headless configuration by calling \(oghma\_core.exe\) directly, then when sim.oghma files from old versions of the model, before running \(oghma\_core.exe\), make sure you have opened it in the GUI first to make sure the file is in the correct format.

6. Tips

If you are not sure where a particular parameter is stored in the OghmaNano sim.json file, a very effective method is to compare two versions of the file and see what changes. One way to do this is to use a file comparison tool such as KDiff3.

The process is straightforward:

1. Open your simulation in the OghmaNano user interface.
2. Adjust the parameter of interest (for example, change the active layer thickness or a voltage setting) and save the simulation.
3. Compare the new sim.json file with the previous version using KDiff3 (or another diff tool).
4. Look for the lines that differ: these will show exactly where in the JSON structure that parameter is stored.

This technique is a quick and reliable way to locate parameters in the JSON if you are unsure of their path in the file. It is especially useful for complex simulations with many nested sections.