Advanced OghmaNano simulation file format reference

This page documents the OghmaNano sim.json file format in detail: the structure of device definitions, electrical and optical material models, Lua scripts, doping, contacts, voltage sweeps, meshing and numerical settings. It also includes a searchable reference of parameter tokens and JSON keys. This is an advanced technical reference, not an introduction to JSON or instructions for opening files in a web browser.

The reference is written for both humans and AI assistants. Human users can consult the tables and examples when editing simulations. AI assistants can use the documented paths and the marked guidance boxes when transforming an existing working simulation into a new device. The same HTML page is the reference for both audiences.

Scope: The nested paths identified as verified come from a working OghmaNano v8.1 example. The token catalogue additionally includes names taken from the supplied parameter dictionary; these are not all necessarily editable paths in every version or simulation type.

1. Using this reference with an AI assistant

This technical reference is intended for both human users and AI assistants creating or modifying OghmaNano simulations. It documents the JSON paths observed in a working OghmaNano v8.1 example and includes the supplied parameter dictionary. This is a reference, not an executable schema or a substitute for a working simulation file. Not every possible device structure or physical model is supported.

The full token catalogue is at section 11. Many dictionary entries are labels for outputs or GUI controls rather than directly editable keys in the supplied sample; an entry in the catalogue is not by itself evidence of an editable JSON path.

2. Top-level objects and simulation selection

The working example also contains the top-level objects electrical_solver, thermal, exciton, fits, parasitic, hard_limit, perovskite, singlet, circuit, gl, gui_config, world, ml and scans, as well as document metadata. The presence and content of these sections can vary across versions and simulation types. Do not delete an unfamiliar section merely because it is not relevant to the new device.

{
  "sim": { "simmode": "segment0@jv" },
  "sims": {
    "jv": {
      "segments": 1,
      "segment0": {
        "config": { "Vstart": 0.0, "Vstop": 2.2, "Vstep": 0.025 }
      }
    }
  }
}

The fragment above illustrates existing paths; it is not a complete simulation file.

3. Segment collections, IDs and data types

Collections are represented by a numeric segments field and consecutively numbered segment0, segment1, … objects. A collection declaring four segments must contain exactly the four corresponding child segment objects. Objects may contain id fields used to identify them. When copying or creating a new object, assign a new unique ID where required; retain IDs for unchanged objects.

{
  "segments": 2,
  "segment0": { "name": "Layer A", "id": "id0123456789abcdef" },
  "segment1": { "name": "Layer B", "id": "idfedcba9876543210" }
}

4. Epitaxy: geometry, composition and doping

Layer definitions are stored at epitaxy.segmentX (with X starting at zero), while contacts are stored separately at epitaxy.contacts.segmentX. In the supplied GaAs working example, y0 is the starting position and dy is the layer thickness, both in metres. Keep layer boundaries contiguous unless the device deliberately includes a physical gap.

A uniform p-type region has positive Na0 and Na1, with Nd0 = Nd1 = 0. A uniform n-type region uses Nd0 and Nd1 instead. An intrinsic region can use zero for all four doping values. Verify whether additional doping or interface fields are active in the selected starting simulation before editing.

5. Electrical Lua material scripts

In the working GaAs example, each semiconductor layer activates its electrical Lua material model using the program object nested under shape_dos. The filename is in default_program_path. The inline program field is an empty string in that example. The script path is relative to the electrical material database, without a leading ./ in the observed example.

"shape_dos": {
  "program": {
    "enabled": "True",
    "program": "",
    "default_program_path": "Inorganic/AlGaAs/AlGaAs.lua",
    "font_size": 12
  }
}

This illustrates the nested script-selection fields. In a real layer, leave all other existing shape_dos fields in place.

Overriding Lua material parameters

OghmaNano allows individual material parameters calculated by Lua scripts to be overridden using epitaxy.segmentX.shape_dos.db_overrides. This allows standard material models to be used while tuning specific parameters, such as recombination rates or carrier mobilities, without modifying the global material database.

For example, to override the radiative recombination coefficient:

"free_to_free_recombination": 1e-16,
"db_overrides": {
    "free_to_free_recombination": "true",
    "Eg": "false",
    "Xi": "false"
}

6. Optical material datasets and emission

The optical dataset for an epitaxial layer is selected in epitaxy.segmentX.absorption.nk_data. The supplied list of optical materials contains paths ending in /alpha.csv; to obtain the directory reference used in nk_data, remove that suffix. The electrical Lua model and optical dataset are separate references and need not have identical paths.

The x = 0.315 optical dataset is a nearby composition approximation for an x = 0.30 AlGaAs electrical model. Do not silently describe it as an exact match. Use the wavelength mesh under optical.mesh.mesh_l when optical calculations require an appropriate spectral range. The example also contains optical.mesh.mesh_y for its optical spatial mesh.

For an electrically driven LED, external optical illumination can be disabled using the existing light-source configuration; the sample contains optical.light_sources.Psun. The layer also contains shape_pl.pl_emission_enabled and related emission settings. Activating emission output is not, by itself, proof that the model resolves spectral line shape, spontaneous emission physics or external quantum efficiency. Confirm which options are supported in the chosen simulation mode.

7. Contacts and voltage polarity

Electrical contacts are defined under epitaxy.contacts, not by changing the doping of an arbitrary layer. The supplied working file has two contacts, with separate nested contact objects. Its top terminal is at y0 and its bottom terminal at y1. The actual voltage orientation follows the applied_voltage_type settings on these terminals.

"contacts": {
  "segments": 2,
  "segment0": {
    "contact": {
      "position": "y0",
      "applied_voltage_type": "change",
      "majority": "hole",
      "minority": "electron",
      "majority_model": "ohmic",
      "minority_model": "ohmic"
    }
  },
  "segment1": {
    "contact": {
      "position": "y1",
      "applied_voltage_type": "ground",
      "majority": "electron",
      "minority": "hole",
      "majority_model": "ohmic",
      "minority_model": "ohmic"
    }
  }
}

Contact fragment: omitted fields are still required in the actual working example.

8. Electrical and optical mesh consistency

For the supplied drift–diffusion example, the electrical y-mesh is under electrical_solver.mesh.mesh_y. Each mesh segment has a len in metres, points, mul, left_right, id and related fields. The optical spatial mesh is a different object under optical.mesh.mesh_y. Changing a layer thickness does not guarantee every mesh setting has been updated.

"mesh_y": {
  "enabled": "True",
  "auto": "True",
  "icon_": "y",
  "segments": 4,
  "segment0": { "len": 2e-7, "points": 30.0 },
  "segment1": { "len": 3e-7, "points": 50.0 },
  "segment2": { "len": 2e-7, "points": 30.0 },
  "segment3": { "len": 1e-7, "points": 20.0 }
}

The fields shown above demonstrate mesh lengths and point counts for an 800 nm four-layer device; this is not a complete mesh_y object.

9. Physical interpretation and unsupported assumptions

A parseable JSON file only establishes syntactic validity. Drift–diffusion transport, material properties, radiative recombination and optics are separate modelling questions. For example, an AlGaAs/GaAs double heterostructure requires appropriate carrier confinement at both interfaces, not merely a plausible-looking layer list. Check the bandgap, electron affinity and transport parameters evaluated by the material scripts at the requested composition and temperature.

More complex devices such as TOPCon solar cells, MOSFETs, bipolar transistors and quantum-well LEDs can require tunnelling, oxide electrostatics, multi-terminal contacts, quantum confinement, interface traps, or additional boundary conditions that a particular starting simulation may not support. If the required physics is not demonstrated by a working example or source documentation, identify the gap instead of inventing JSON fields. Optical emission calculations should not be presented as calibrated device efficiency without suitable recombination and extraction models.

10. Validation checklist and troubleshooting

After editing a simulation file, validate the JSON syntax, the structure of all segment collections, key types relative to the base file, and any device-specific physical constraints. For example, the following Python snippet checks ordinary segments collections without requiring any OghmaNano APIs. It does not guarantee that OghmaNano will run the model.

import json
import re
from pathlib import Path

sim = json.loads(Path("sim.json").read_text(encoding="utf-8"))

def check_segments(obj, location="root"):
    if isinstance(obj, dict):
        if isinstance(obj.get("segments"), int):
            count = obj["segments"]
            actual = {
                int(key[7:]) for key in obj
                if re.fullmatch(r"segment[0-9]+", key)
            }
            expected = set(range(count))
            if actual != expected:
                raise ValueError((location, count, sorted(actual)))
        for key, value in obj.items():
            check_segments(value, location + "." + key)

check_segments(sim)
print("JSON and segment counts look consistent")

If a token’s JSON location or meaning is unclear, edit that control in the graphical interface, save the file, and compare the before/after sim.json files. This is more reliable than inferring paths from parameter names alone.

11. Complete OghmaNano JSON token reference (A–Z)

This is the single, searchable reference for OghmaNano parameter tokens and JSON structural keys. It combines all 985 entries from the supplied parameter dictionary with 382 additional keys observed in the working OghmaNano v8.1 sim.json example. All 1,367 rows are organised together alphabetically: there is no separate list to consult for structure or material scripts.

Descriptions, units and declared options for dictionary tokens come from the supplied dictionary. Keys found only in the working simulation are included with conservative descriptions where meaning is unverified. A listed JSON path and data type are observations from a working example, not a promise that the same name is valid at every location or in every OghmaNano version. Some tokens are output fields or user-interface controls rather than editable simulation inputs. Three dictionary entries (Ra[0-9], Rq[0-9] and Rp[0-9]) are token patterns.