8. Input Files

PhonoMC accepts only sectioned TOML files. Top-level key aliases, legacy text files, unknown sections, unknown keys, duplicate keys, and invalid scalar types are rejected.

8.1. Canonical sections

The supported sections are:

  • [geometry]

  • [simulation]

  • [boundary]

  • [heat_source]

  • [io]

8.2. [geometry]

model

"box" or a path to an STL/OBJ mesh. Relative paths are resolved from the working directory first and then from the input-file directory.

sizes

Required for model = "box". Exactly three positive values [x,y,z] in nm.

merge_coplanar_facets

Optional boolean, default true. Connected coplanar triangles are treated as one facet when enabled.

Example:

[geometry]
model = "box"
sizes = [100, 100, 100]
merge_coplanar_facets = true

8.3. [simulation]

particle_count

Positive particle count. Default: 10000.

time_step

Positive time step in ps. Default: 1.0.

iterations

Positive integer number of time steps. Default: 10000.

random_seed

Unsigned 64-bit seed used to derive the initial, injection, and OpenMP random streams. Default: 12345. Reusing the seed reproduces a run when the executable, input, and OpenMP thread configuration are unchanged.

grid_xyz

Required positive integer grid dimensions [nx,ny,nz].

initial_temperature

Either an unquoted numeric temperature in K or "linear". Linear mode interpolates between the coldest and hottest valid thermal reservoirs.

compute_kappa

Enable conductivity estimates. Automatically disabled when a volumetric heat source is enabled.

convergence_write_interval

Positive integer output stride. Default: 10.

profile_timers

Write solver timing diagnostics when true.

progress_temperature_summary_only

Print only Tmin/Tavg/Tmax instead of every grid temperature.

temperature_lookup_dt

Positive lookup-table temperature step in K. Default: 0.1.

background_temperature_mode / lifetime_temperature_mode

"local" or "fixed".

background_temperature / lifetime_temperature

Non-negative fixed temperatures used when the corresponding mode is "fixed".

8.4. [boundary]

Boundary regions use relative coordinates in the domain bounding box:

[xmin,ymin,zmin,xmax,ymax,zmax]

Three arrays must have identical lengths:

boundary_position

Region selectors. Every declared region must match at least one mesh facet.

boundary_conditions

One code per region: "T" thermal reservoir, "P" periodic, or "R" rough boundary.

boundary_values

Temperature in K for T, roughness in nm for R, and exactly 0 for P.

periodic_pair

Every periodic region must appear exactly once. Entries are grouped into pairs, and paired facets must have opposite normals and compatible areas and boundary-edge lengths.

Later boundary regions take precedence if selectors overlap. Prefer non-overlapping selectors unless deliberate precedence is required.

Example:

[boundary]
boundary_position = [
  [-0.01, 0, 0, 0.01, 1, 1],
  [ 0.99, 0, 0, 1.01, 1, 1],
  [0, -0.01, 0, 1, 0.01, 1],
  [0,  0.99, 0, 1, 1.01, 1]
]
boundary_conditions = ["T", "T", "P", "P"]
boundary_values = [301, 299, 0, 0]
periodic_pair = [
  [0, -0.01, 0, 1, 0.01, 1],
  [0,  0.99, 0, 1, 1.01, 1]
]

8.5. [heat_source]

enabled

Enable local volumetric particle injection.

profile

"uniform" or "gaussian".

power_density

W/m³. For Gaussian sources this is the peak value.

8.5.1. Uniform profile keys

min and max define opposite corners of a relative region.

[heat_source]
enabled = true
profile = "uniform"
min = [0.3, 0.6, 0.7]
max = [0.7, 0.8, 1.0]
power_density = 1.0e20

8.5.2. Gaussian profile keys

center and sigma are relative coordinates. A non-positive sigma makes that axis uniform.

[heat_source]
enabled = true
profile = "gaussian"
center = [0.5, 0.7, 1.0]
sigma = [0.0, 0.04, 0.10]
power_density = 1.0e20

8.6. [io]

material_folder

Path to a directory containing a valid POSCAR and HDF5 material file.

output_folder

Base result path. PhonoMC appends _0, _1, and so on.

[io]
material_folder = "../material/Si/"
output_folder = "results/Cross_100nm/"

8.7. Strict validation summary

  • use only literal TOML booleans true and false

  • do not quote numeric initial_temperature values

  • use integer, positive grid_xyz dimensions

  • keep all boundary arrays aligned

  • use finite, non-negative thermal and roughness values

  • assign every periodic facet to exactly one valid pair

  • provide valid POSCAR and HDF5 material data