API Reference

Core package

Qt application entry point for Magboltz-GUI.

magboltz_gui.main.main()[source]

Create the application, show the main window, and enter the event loop.

Return type:

None

Data model

Static gas catalogue used by the mixture editor.

class magboltz_gui.data.database.GasItem(id, name, formula, year, note, rating)[source]

One gas entry loaded from the bundled CSV catalogue.

Parameters:

  • id (int)

  • name (str)

  • formula (str | None)

  • year (int | None)

  • note (str | None)

  • rating (int | None)

id: int
name: str
formula: str | None
year: int | None
note: str | None
rating: int | None
property as_name: str
property as_name_formula: str
property as_formula: str
class magboltz_gui.data.database.GasDatabase(content=<factory>)[source]

In-memory lookup table for gas definitions.

Parameters:

content (List[GasItem])

content: List[GasItem]
load(filepath)[source]

Load gas definitions from a CSV file.

Parameters:

filepath (Path)

Return type:

None

get(id)[source]

Return one gas definition by numeric Magboltz id.

Parameters:

id (int)

Return type:

GasItem

Typed representation of the Magboltz input-card format.

class magboltz_gui.data.input_cards.InputGas(gas_id, gas_frac)[source]

One gas component in the current mixture.

Parameters:

  • gas_id (int)

  • gas_frac (float)

gas_id: int
gas_frac: float
class magboltz_gui.data.input_cards.InputCards(number_of_real_collisions=5, enable_penning=False, enable_thermal=True, final_energy=0.0, gas_temperature=20.0, gas_pressure=760.0, electric_field=1000.0, magnetic_field=0.0, angle=0.0, gases=<factory>)[source]

Editable subset of the Magboltz input cards exposed by the GUI.

Parameters:

  • number_of_real_collisions (int)

  • enable_penning (bool)

  • enable_thermal (bool)

  • final_energy (float)

  • gas_temperature (float)

  • gas_pressure (float)

  • electric_field (float)

  • magnetic_field (float)

  • angle (float)

  • gases (List[InputGas])

property number_of_gases: int

Return the current number of gas components.

number_of_real_collisions: int = 5
enable_penning: bool = False
enable_thermal: bool = True
final_energy: float = 0.0
gas_temperature: float = 20.0
gas_pressure: float = 760.0
electric_field: float = 1000.0
magnetic_field: float = 0.0
angle: float = 0.0
gases: List[InputGas]

Parsing and result model

Read and write Magboltz card files from the GUI data model.

magboltz_gui.util.parser.load(filename)[source]

Parse one Magboltz card file into an InputCards object.

Parameters:

filename (Path)

Return type:

InputCards

magboltz_gui.util.parser.save(input_cards, filename)[source]

Serialize InputCards back to the Magboltz card format.

Parameters:
Return type:

None

Structured result model for parsed Magboltz runs and exports.

class magboltz_gui.util.run_result.RunMeta(tool_name='magboltz', tool_version=None, timestamp_utc=None, gui_version=None, schema_version='1.0')[source]

Metadata describing the tool version and capture time.

Parameters:

  • tool_name (str)

  • tool_version (str | None)

  • timestamp_utc (str | None)

  • gui_version (str | None)

  • schema_version (str)

tool_name: str = 'magboltz'
tool_version: str | None = None
timestamp_utc: str | None = None
gui_version: str | None = None
schema_version: str = '1.0'
class magboltz_gui.util.run_result.RunInput(input_text=None, input_path=None)[source]

Original input text and filesystem origin of one run.

Parameters:

  • input_text (str | None)

  • input_path (str | None)

input_text: str | None = None
input_path: str | None = None
class magboltz_gui.util.run_result.RunIntegration(E_min_eV=None, E_max_eV=None, n_steps=None)[source]

Energy integration settings reported by Magboltz.

Parameters:

  • E_min_eV (float | None)

  • E_max_eV (float | None)

  • n_steps (int | None)

E_min_eV: float | None = None
E_max_eV: float | None = None
n_steps: int | None = None
class magboltz_gui.util.run_result.RunFlags(penning_included=None, thermal_motion_included=None, anisotropic_scattering_type=None, short_decorrelation_length_collisions=None)[source]

Boolean and integer flags affecting the simulation model.

Parameters:

  • penning_included (bool | None)

  • thermal_motion_included (bool | None)

  • anisotropic_scattering_type (int | None)

  • short_decorrelation_length_collisions (int | None)

penning_included: bool | None = None
thermal_motion_included: bool | None = None
anisotropic_scattering_type: int | None = None
short_decorrelation_length_collisions: int | None = None
class magboltz_gui.util.run_result.RunConditions(gas_temperature_C=None, gas_pressure_torr=None, electric_field_V_cm=None, magnetic_field_kG=None, angle_E_B_deg=None, cyclotron_freq_rad_ps=None, initial_electron_energy_eV=None, integration=<factory>, flags=<factory>)[source]

Physical and numerical conditions used for one run.

Parameters:

  • gas_temperature_C (float | None)

  • gas_pressure_torr (float | None)

  • electric_field_V_cm (float | None)

  • magnetic_field_kG (float | None)

  • angle_E_B_deg (float | None)

  • cyclotron_freq_rad_ps (float | None)

  • initial_electron_energy_eV (float | None)

  • integration (RunIntegration)

  • flags (RunFlags)

gas_temperature_C: float | None = None
gas_pressure_torr: float | None = None
electric_field_V_cm: float | None = None
magnetic_field_kG: float | None = None
angle_E_B_deg: float | None = None
cyclotron_freq_rad_ps: float | None = None
initial_electron_energy_eV: float | None = None
integration: RunIntegration
flags: RunFlags
class magboltz_gui.util.run_result.MixtureGas(name, model_tag, fraction_percent)[source]

One gas entry reconstructed from the run summary.

Parameters:

  • name (str)

  • model_tag (str | None)

  • fraction_percent (float | None)

name: str
model_tag: str | None
fraction_percent: float | None
class magboltz_gui.util.run_result.RunCounts(total_real_collisions=None, num_null_collisions=None, calculated_max_collision_time_ps=None, null_collision_frequency_components=<factory>)[source]

Collision counters and related summary values.

Parameters:

  • total_real_collisions (int | None)

  • num_null_collisions (int | None)

  • calculated_max_collision_time_ps (float | None)

  • null_collision_frequency_components (List[float])

total_real_collisions: int | None = None
num_null_collisions: int | None = None
calculated_max_collision_time_ps: float | None = None
null_collision_frequency_components: List[float]
class magboltz_gui.util.run_result.DriftVelocity(v_um_ns=None, err_pct=None)[source]

One drift-velocity component with its uncertainty.

Parameters:

  • v_um_ns (float | None)

  • err_pct (float | None)

v_um_ns: float | None = None
err_pct: float | None = None
class magboltz_gui.util.run_result.DiffusionComponent(value=None, err_pct=None)[source]

One diffusion observable with an uncertainty percentage.

Parameters:

  • value (float | None)

  • err_pct (float | None)

value: float | None = None
err_pct: float | None = None
class magboltz_gui.util.run_result.RunDiffusion(transverse=<factory>, longitudinal=<factory>)[source]

Grouped transverse and longitudinal diffusion quantities.

Parameters:
transverse: Dict[str, DiffusionComponent]
longitudinal: Dict[str, DiffusionComponent]
class magboltz_gui.util.run_result.RunTransport(vx_um_ns=None, vy_um_ns=None, vz_um_ns=None, diffusion=<factory>, ionisation_rate_per_cm=None, ionisation_rate_err_pct=None, attachment_rate_per_cm=None, attachment_rate_err_pct=None, mean_electron_energy_eV=None, mean_electron_energy_err_pct=None)[source]

Transport observables extracted from the output.

Parameters:

  • vx_um_ns (DriftVelocity | None)

  • vy_um_ns (DriftVelocity | None)

  • vz_um_ns (DriftVelocity | None)

  • diffusion (RunDiffusion)

  • ionisation_rate_per_cm (float | None)

  • ionisation_rate_err_pct (float | None)

  • attachment_rate_per_cm (float | None)

  • attachment_rate_err_pct (float | None)

  • mean_electron_energy_eV (float | None)

  • mean_electron_energy_err_pct (float | None)

vx_um_ns: DriftVelocity | None = None
vy_um_ns: DriftVelocity | None = None
vz_um_ns: DriftVelocity | None = None
diffusion: RunDiffusion
ionisation_rate_per_cm: float | None = None
ionisation_rate_err_pct: float | None = None
attachment_rate_per_cm: float | None = None
attachment_rate_err_pct: float | None = None
mean_electron_energy_eV: float | None = None
mean_electron_energy_err_pct: float | None = None
class magboltz_gui.util.run_result.RunFrequenciesTotal(total_coll_freq_1e12_s=None, elastic_coll_freq_1e12_s=None, inelastic_coll_freq_1e12_s=None, ionisation_coll_freq_1e12_s=None, attachment_coll_freq_1e12_s=None)[source]

Global collision-frequency summary from the run output.

Parameters:

  • total_coll_freq_1e12_s (float | None)

  • elastic_coll_freq_1e12_s (float | None)

  • inelastic_coll_freq_1e12_s (float | None)

  • ionisation_coll_freq_1e12_s (float | None)

  • attachment_coll_freq_1e12_s (float | None)

total_coll_freq_1e12_s: float | None = None
elastic_coll_freq_1e12_s: float | None = None
inelastic_coll_freq_1e12_s: float | None = None
ionisation_coll_freq_1e12_s: float | None = None
attachment_coll_freq_1e12_s: float | None = None
class magboltz_gui.util.run_result.CollisionProcess(label, eloss_eV, freq_1e12_s, err_pct, category=None)[source]

One process contribution in the per-gas collision-frequency tables.

Parameters:

  • label (str)

  • eloss_eV (float | None)

  • freq_1e12_s (float | None)

  • err_pct (float | None)

  • category (str | None)

label: str
eloss_eV: float | None
freq_1e12_s: float | None
err_pct: float | None
category: str | None = None
class magboltz_gui.util.run_result.GasFrequencies(gas_name, processes=<factory>)[source]

Collision-frequency breakdown for one gas species.

Parameters:
gas_name: str
processes: List[CollisionProcess]
class magboltz_gui.util.run_result.ConvergenceRow(vel, pos, time, energy, count, difxx, difyy, difzz)[source]

One row of the Magboltz convergence table.

Parameters:

  • vel (float)

  • pos (float)

  • time (float)

  • energy (float)

  • count (float)

  • difxx (float)

  • difyy (float)

  • difzz (float)

vel: float
pos: float
time: float
energy: float
count: float
difxx: float
difyy: float
difzz: float
class magboltz_gui.util.run_result.EnergyRow(E_eV, spec, bin_width_eV=None)[source]

One row of the energy-distribution table.

Parameters:

  • E_eV (float)

  • spec (float)

  • bin_width_eV (float | None)

E_eV: float
spec: float
bin_width_eV: float | None = None
class magboltz_gui.util.run_result.RunTables(convergence_table=<factory>, energy_distribution=<factory>, units=<factory>)[source]

Tabular output sections captured from the run.

Parameters:
convergence_table: List[ConvergenceRow]
energy_distribution: List[EnergyRow]
units: Dict[str, str]
class magboltz_gui.util.run_result.RunRaw(stdout_text=None, parser_warnings=<factory>)[source]

Raw stdout plus parser warnings kept for debugging and export.

Parameters:

  • stdout_text (str | None)

  • parser_warnings (List[str])

stdout_text: str | None = None
parser_warnings: List[str]
class magboltz_gui.util.run_result.RunResult(meta=<factory>, input=<factory>, conditions=<factory>, mixture=<factory>, counts=<factory>, transport=<factory>, frequencies_total=<factory>, frequencies_by_gas=<factory>, tables=<factory>, raw=<factory>)[source]

Top-level result object used across plotting and export code.

Parameters:
meta: RunMeta
input: RunInput
conditions: RunConditions
mixture: List[MixtureGas]
counts: RunCounts
transport: RunTransport
frequencies_total: RunFrequenciesTotal
frequencies_by_gas: List[GasFrequencies]
tables: RunTables
raw: RunRaw
to_dict()[source]

Recursively convert the result tree into plain Python containers.

Return type:

Dict[str, Any]

Parse raw Magboltz stdout into the structured run-result model.

magboltz_gui.util.output_parser.parse_magboltz_output(stdout_text, input_text=None, input_path=None)[source]

Extract transport quantities, tables, and metadata from one Magboltz run.

Parameters:

  • stdout_text (str)

  • input_text (str | None)

  • input_path (str | None)

Return type:

RunResult

Export

class magboltz_gui.util.export_types.ExportType(*values)[source]
SUMMARY = 'summary'
CONVERGENCE_TABLE = 'convergence_table'
ENERGY_DISTRIBUTION = 'energy_distribution'
COLLISION_FREQUENCIES = 'collision_frequencies'
FULL_RUN_ARCHIVE = 'full_run'
class magboltz_gui.util.export_types.ExportFormat(*values)[source]
CSV = 'csv'
JSON = 'json'
XML = 'xml'
class magboltz_gui.util.export_types.CsvOptions(delimiter: 'str' = ',', include_units: 'bool' = True, include_metadata: 'bool' = True, flatten_mixture: 'bool' = True)[source]
Parameters:

  • delimiter (str)

  • include_units (bool)

  • include_metadata (bool)

  • flatten_mixture (bool)

delimiter: str = ','
include_units: bool = True
include_metadata: bool = True
flatten_mixture: bool = True
class magboltz_gui.util.export_types.JsonOptions(include_input_text: 'bool' = True, include_raw_stdout: 'bool' = False, include_parser_warnings: 'bool' = True, pretty_print: 'bool' = True)[source]
Parameters:

  • include_input_text (bool)

  • include_raw_stdout (bool)

  • include_parser_warnings (bool)

  • pretty_print (bool)

include_input_text: bool = True
include_raw_stdout: bool = False
include_parser_warnings: bool = True
pretty_print: bool = True
class magboltz_gui.util.export_types.XmlOptions(include_input_text: 'bool' = True, include_raw_stdout: 'bool' = False, include_parser_warnings: 'bool' = True)[source]
Parameters:

  • include_input_text (bool)

  • include_raw_stdout (bool)

  • include_parser_warnings (bool)

include_input_text: bool = True
include_raw_stdout: bool = False
include_parser_warnings: bool = True

Export parsed run results to CSV, JSON, and XML representations.

magboltz_gui.util.export_controller.available_export_types(run)[source]

Return the export modes that make sense for the current result.

Parameters:

run (RunResult)

Return type:

List[ExportType]

magboltz_gui.util.export_controller.export_csv(run, export_type, path, opts)[source]

Write one export view to CSV.

Parameters:
Return type:

None

magboltz_gui.util.export_controller.export_json(run, export_type, path, opts)[source]

Write one export view to JSON.

Parameters:
Return type:

None

magboltz_gui.util.export_controller.export_xml(run, export_type, path, opts)[source]

Write one export view to XML.

Parameters:
Return type:

None

magboltz_gui.util.export_controller.export_to_file(run, export_type, export_format, path, csv_options=None, json_options=None, xml_options=None)[source]

Dispatch one export request to the format-specific writer.

Parameters:
Return type:

None

magboltz_gui.util.export_controller.default_filename(run, export_type, ext)[source]

Build a default filename for one exported artefact.

Parameters:
Return type:

str

Runtime helpers

Manage one live Magboltz subprocess connected to the GUI.

class magboltz_gui.util.process.ProcessManager(main_window)[source]

Own one QProcess and bridge it with the main window state.

Parameters:

main_window (MagboltzGUI)

run()[source]

Create the process, wire its signals, and launch it.

Return type:

None

stop()[source]

Attempt a graceful stop, then fall back to killing the process.

Return type:

None

run_process()[source]

Start magboltz and stream the current input card to stdin.

Return type:

None

handle_stdout()[source]

Append standard output to the console view and capture buffer.

Return type:

None

handle_stderr()[source]

Append standard error to the console view.

Return type:

None

process_finished()[source]

Parse the finished run and update export/plot availability.

Return type:

None

magboltz_gui.util.platform.ensure_qt_runtime_or_explain()[source]
Return type:

None

Linux Qt styling helper.

Why this exists

  • On GNOME/Wayland with system PyQt6, Qt may not find a platform theme plugin and falls back to the bare “Fusion” style, making widgets look disabled/flat.

  • Users can fix it via env vars (QT_QPA_PLATFORMTHEME/QT_STYLE_OVERRIDE), but we add a light-touch, auto-detect fallback so the app looks usable out of the box.

Principles

  • Never override user choices: if env vars are already set, do nothing.

  • Only set a platform theme if the matching plugin is actually present.

  • Prefer qt6ct (good GNOME integration), then gtk3; otherwise leave defaults.

  • After QApplication is created, nudge the style away from Fusion if a better style is available.

magboltz_gui.util.qt_style.set_linux_platform_theme_env_if_available()[source]

If on Linux and the user hasn’t set QT_QPA_PLATFORMTHEME, set it to a detected platform theme plugin (qt6ct or gtk3) when available.

Return type:

None

magboltz_gui.util.qt_style.apply_linux_style_fallback(app)[source]

If on Linux and the user hasn’t set QT_STYLE_OVERRIDE, try to pick a better style than Fusion when available.

Parameters:

app (object)

Return type:

None

Icon theme helper for Linux.

Why

  • When using system Qt with platform themes like qt6ct, Qt may not pick up the desktop icon theme automatically, causing themed icons (document-open, etc.) to appear blank.

  • We add a lightweight fallback that keeps user overrides intact and only acts if no themed icons are found.

Behavior

  • Linux-only.

  • Does nothing if any standard theme icon is already available.

  • Otherwise, sets theme search paths to include common system icon dirs plus our package icons, and picks a sensible default theme (Adwaita) if present.

magboltz_gui.util.icon_theme.ensure_icon_theme()[source]
Return type:

None