FLOOXS » TclLib » Models

Models — TclLib Procs

62 documented proc(s) in TclLib/Models/.

::$ · ::BandStructure::__assign_family_shifts · ::BandStructure::__compose_flat · ::BandStructure::__compose_multivalley · ::BandStructure::__hole_solution_name · ::BandStructure::__lowest_affinity · ::BandStructure::Varshni::stamp · ::Device::__append_flag_token · ::Device::__flag_present · ::Device::__render_const · ::Device::__render_pde · ::Device::consume · ::Device::dict_deep_merge · ::Device::is_dict · ::Device::render · ::Device::resolve_models · ::Generation::Avalanche::vanOberstraeten::__tanh · ::Generation::B2B::MultiBandSchenk::compose · ::Generation::B2B::Schenk::compose · ::Mobility::Farahmand::hole · ::Mobility::Kanda::__wrap · ::Mobility::Klaassen::__build · ::Mobility::Klaassen::__build_dopant · __cubic_stiffness · __device_bool · __device_get · __device_parse_args · __internal_substrate_fill_lines · __pack_aniso_result · __stress_parse_args · _carrier_slice · arr · build_chemistry · cij_atensor · cij_stensor · clear_chemistry · ConcBind · device · DiffLimit · elastic_init · elastic_variant · init_adapt_fields · MatBandGap · MatNcTotal · MatNvTotal · matparam_proc · matparam_sub · matparam_sub3 · models_chain_get · pde_append · pde_flush · pde_init · pde_keys · pde_peek · pde_set_self · set_aniso_elastic · set_transverse_iso_elastic · stress · stress_canonical_variants · stress_known_bases · stress_pull · SurfDiffLimit

`<Mat>::ElasticInit` is the auto-load trigger that StressPackage's
`stress_known_bases` scan finds in auto_index.  Emitted dynamically
so the per-material file stays data + one declarator line.

Strain shift assignment per valley family.  Stores into the upvar'd
shifts array.  X-family valleys get XBandEdgeShiftStrain entries
indexed by their |Dir|; L-family valleys get LBandEdgeShiftStrain;
Γ-family valleys get a (currently zero) hydrostatic shift.

Single-effective-band emission.

Multi-valley emission (lifted from BandstructurePackage steps
2/4/5/7/8/10 as pure function).

Map schema band names (LH/HH/SO) to the legacy solution names that
downstream code (avalanche, B2B, Schenk) reads.  Unknown band names
pass through verbatim so materials can introduce additional bands.

Compute χ_lowest = max(χ_v) across all valleys, as a nested-ternary
Alagator expression.  Deduplicates identical χ's so a 6-valley
X-only material with shared χ produces a trivial constant.

::BandStructure::Varshni::stamp mat params T x_expr

Composer-side stamper.  Stamps the three matparam keys MatBandGap
reads (`VarshniEg0`, `VarshniAlpha`, `VarshniBeta`) onto the
material's namespace.  Composition rules in any of the three values
are evaluated via `::Compose::eval_value` with `$x_expr` substituted
into the rule output.

Strict consumption: unknown keys raise (delegated to `expression`'s
validation).  Missing essentials raise at MatBandGap emit time.

Side effect only — returns nothing.  Use `::BandStructure::Varshni::
expression` directly to build the Alagator Eg(T) string from the
stamped values.

Internal: append a flag token to the tokens list, handling
`dampval=<v>` and bare keyword forms.

Internal: does a flag (literal token) appear in the flags list?

::Device::__render_const — emit a `solution $mat add name=$name const
<flags> val=$val` call.

::Device::__render_pde — emit a `solution $mat add name=$name pde
<flags> val=$val` call.

::Device::consume <dictvar> <key> ?<default>?

Reads and removes a key from a dict variable in one shot.  Returns
the value (or $default if the key is absent).  This is how the
top-level dispatcher implements consume-and-validate: each family
entry is read and removed as it dispatches; any unconsumed key at
the end raises.

::Device::dict_deep_merge <parent> <child>

Recursive leaf-level merge.  At each level: if a key exists in both
parent and child AND both values are themselves dicts, recurse.
Otherwise child wins.

::Device::is_dict <value>

Heuristic: a Tcl value is "dict-like" if it has even length AND
`dict size` succeeds on it.  Used to decide whether deep_merge
should recurse at this level or treat the value as a leaf.  Lists
(like Dir = {1 0 0}) have odd length only for odd-element lists,
so {Dir {1 0 0}} treats the {1 0 0} as 1-element dict at this
heuristic — accepted because {1 0 0} merging never recurses into
0/0 the way leaf-overrides need.  Acceptable false-positive for
the rare 3-element direction value.

A cleaner alternative is to mark dict values explicitly, but the
heuristic works for every value shape FLOOXS actually uses.

::Device::render <mat> <decls>

Iterate decls (a dict of name → spec) and emit one `solution $mat
add ...` call per entry.  The order is dict-iteration order, which
in Tcl is insertion order, which equals the order the upstream
compose procs returned their spec dicts.  Per-material registration
semantics; cross-material solutions stay outside this composer
(FEQFDevicePackage sets them up before the pull walks materials).

::Device::resolve_models <mat>

Returns the effective ::Models dict for $mat — recursive deep merge
of every link in `mater name=$mat chain` (root first, child last,
so child values win at leaf level).  Materials with no ::Models
entry contribute nothing to the merge.

Returns an empty dict if no link in the chain has a ::Models entry.

Internal: hyperbolic tangent as an Alagator expression.

::Generation::B2B::MultiBandSchenk::compose mat T params
  Returns {SchenkSRH {…} Schenk {…}} spec-dict.  Schenk references
  multi-valley DeltaE100/010/001 + DeltaELH/HH/SO solutions emitted
  by BandStructure::compose's multi-valley path.

::Generation::B2B::Schenk::compose mat T params
  Returns {SchenkSRH {…} Schenk {…}} spec-dict.

Farahmand is electron-only.  Hole mobility for III-N materials is
typically a scalar — declared via Mobility { Constant { hole { mu <v> } } }
alongside Farahmand's electron entry.

Internal: build the Kanda per-axis wrap for one carrier.  `base_mu`
is the upstream scalar mobility expression (output of Mathiessen
sum + any prior wraps like Canali).

Internal: build full Klaassen mobility for one (material, carrier).
Walks the dopants sub-dict, builds one per-dopant Klaassen expression
per fully-declared dopant, Mathiessen-sums them.

Internal: build Klaassen mobility for one (material, carrier, dopant)
slice.  Used by __build below; returns the per-dopant Alagator string
or "" when the dopant's params are incomplete.

Cubic 6x6 stiffness matrix in crystal frame from C11, C12, C44.

Internal helper: boolean flag presence (returns 1 if set to non-zero).

Internal helper: pull a flag value from the parsed dict, with default.

Internal: parse a device-style args list into a dict of (flag, value).
  `bareword`     → value 1
  `!bareword`    → value 0
  `key=value`    → value
  `key=`  `value`→ value   (split-token form, used in legacy code)

Exact-token matching only — no substring false positives from `t.init`
masquerading as `init`.  Iterate the list directly without string
mapping so brace-quoted values (movie={...long Tcl callback...})
preserve their grouping semantics.

Internal helper: given a sorted unique list of required positions plus
a target gap, return a denser list with intermediate fill points so
every consecutive pair is within `target`.

Pack a rotated 6x6 stiffness matrix + the three 2D-RHS compliance entries
into the 15-element list expected by cij_atensor / cij_stensor:
  c00 c01 c02 c10 c11 c12 c20 c21 c22 c33 c44 c55 s02 s12 s22
where c33/c44/c55 in the output correspond to C(5,5), C(3,3), C(4,4) — the
C++ stress.cc ordering (re-orders shears xy/yz/zx).

Internal flag parser: same logic as DeviceWrapper's parser but stress
only has one bareword flag (`calcstress` / `!calcstress`).  Iterate
the args list directly so brace-quoted values survive.

Internal helper: extract a model dict's carrier slice (electron or
hole sub-dict).  Returns "" if the carrier isn't declared for this
model.

Numeric Arrhenius helper: pre * exp(-act / kT).  Tcl-time evaluation
(distinct from the Alagator `[Arrhenius {…} …]` literal that DiffLimit /
ConcBind / SurfDiffLimit return).  Used by the dopant param declarers
in TclLib/Device/Silicon/Dopants/Params/ to replace the per-file
`proc _Arr` + `rename _Arr ""` workaround.

Three-phase build driver.  With -mater Mat, restricts phases 1+2 to
(Mat, Sol) registrations for that material AND the flush to that material
too.  Without it, runs everything.

Full anisotropic ATensor: twelve independent constants from the rotated
6x6 stiffness matrix.

Isotropic-by-symmetry STensor: three independent constants
c00 (longitudinal), c01 (off-diagonal), c22 (shear). Takes the full
15- or 12-element list returned by set_aniso_elastic; ignores all but
the relevant entries.

Remove all chemistry registrations.  Useful at the start of a deck that
wants a clean slate.

Concentration-binding equilibrium: lattice density × exp(entropy)
× exp(-binding/kT).  Returns a `[Arrhenius {…} …]` literal.

device — TCAD-side wrapper that translates legacy device-command
flag sets into `solve <mode>` calls.  Subcommands:
  device pull T=… miller=…   pull-mode equation setup
  device init                soft reset + steady solve
  device                     steady solve
  device freq=Hz [complex]   AC small-signal
  device time=s […]          transient
  device store|restore|clear DC checkpoint primitives
Forwards everything else to `solve` with the appropriate mode.

Diffusion-limited reaction rate constant for capture of $Species by $Mat.
Returns a literal `[Arrhenius {(4π Σ D0 · Lspa)} barrier]` string.

Generic elastic_init: declare $mat (with its parent chain) if not
already in `mater list`.  Walks $::Elastic::ParentOf upward until it
hits a root (parent == "").  Idempotent — a re-call on an already-
declared material is a no-op.

If a chain link hasn't been sourced yet, auto-load its ElasticInit
(which sources its ElasticEquations.tcl and registers via
`elastic_base`).  This is what makes a chain like Oxide → BaseMat work
when Oxide's file is loaded first.

Register a deck-level variant material that inherits elastic data from
a base.  `<variant>` doesn't get added to `mater list` here — that
happens in StressPackage's stress_canonical_variants after all parents
have been initialized.  This is the bottom-up replacement for the
hardcoded variant→parent table that used to live in StressPackage.tcl.

Substeps 3a + 3b fields.  Additional Grid.* fields are added by later
Phase-3 substeps (ShrinkEarly, ShrinkLate, GridAddPerp, Refine.Stop, ...).

perp.add.dist / Max.Radius / bound.add.dist / Corner.Add are only read by
the growing-mesh GridAdd path (LCOV_EXCL'd in coverage today, since the
active deposit goes through DepLvl which calls GridUpd(do_add=0)).
Defaults track the historical 0.1*UnitScl values; decks override with
`sel z=<expr>*Mater(SomeMat) ...` for per-material scoping.

Build the Varshni temperature-dependent bandgap expression for a
material.  Returns an Alagator string Eg0 - α·T² / (T+β) safe to
embed in `solution add name=Eg val=…`.  Used by the per-material
`<Mat>::BandGap` accessor shims.

Material-effective Nc: Σ over all declared conduction valleys of
`BandEdgeNumberOfStates T= m=(ml·mt²)^(1/3)`.  Useful for decks /
tests that want a single per-material Nc rather than the per-valley
decomposition the dispatcher emits.

Material-effective Nv: Σ over all declared hole bands of
`BandEdgeNumberOfStates T= m=<band m>`.

matparam_proc — chain-walking proc resolver.

Symmetric to matparam (which walks the chain for data) — walks the inherit
chain looking for a proc named ::<link>::<proc_name> and returns its fully
qualified name (e.g. ::Silicon::ConductionTensorHook).  Returns "" if no
link in the chain defines the proc.  Forces auto_load on each candidate
before testing existence so a chain link whose source file hasn't loaded
yet still resolves.

Used by the DriftDiffusionPackage dispatcher so a child material
inheriting Silicon picks up Silicon's ConductionTensorHook /
ValenceTensorHook / ValenceStrainHook automatically — no per-variant
proc required.

Same shape but for nested per-species namespaces.  Used by chemistry:
parameters live at ::<mat>::<sub>::<key> where <sub> is the species name.
Example: matparam_sub Silicon Smic Bind  => $::Silicon::Smic::Bind.

Four-deep variant: ::<mat>::<sub>::<def>::<key>.  Used by the dopant library
where per-(dopant, defect) params live at ::<Mat>::<Dopant>::<Defect>::<Key>
(e.g. ::Silicon::Boron::Int::Binding).  Closes the gap left by Dopant.tcl's
dopant_has2 / dopant_get2 helpers, which read the literal 4-deep namespace
without walking the inherit chain — meaning a SiGe-derived deck couldn't
inherit Silicon's per-(dopant, defect) params without redeclaring them all.

models_chain_get — chain-walking dict accessor on ::Models.

Walks `mater name=$mat chain` and returns the dict slice at the given
path for the FIRST link in the chain that has it.  Returns "" when no
link in the chain has that path (or ::Models is unset).  The dict
analog of matparam — instead of looking up ::<link>::<key>, it does
`dict get $::Models <link> <args>`.

Used by the pull-mode TCAD composers (e.g. __compose_elasticity) so a
child material inheriting Silicon picks up Silicon's Elasticity slice
automatically when the child has no override of its own — no
per-variant data declaration required.

Examples (assuming SiGech inherits Silicon, both via `mater inherit=`):
  dict set ::Models Silicon Elasticity Anisotropic {C11 165.6e10 ...}
  models_chain_get SiGech Elasticity                   ;# → {Anisotropic {C11 165.6e10 ...}}
  models_chain_get SiGech Elasticity Anisotropic C11   ;# → 165.6e10
  models_chain_get Polysilicon Elasticity              ;# → "" (no chain link declares Elasticity)

---- APPEND (cross-coupling fragment) ----
The fragment is expected to be sign-prefixed: "+ X" / "- Y".  Empty-slot
semantics: store as "0 fragment" so the equation parses cleanly even before
the self-contribution is added.

---- FLUSH ----
Emits one `solution <Mat> name=<Sol> pde value="<accumulator>"` per
populated slot.  With -mater <Mat>, restricts emission to that material.
The flush is a side-effect — it doesn't clear the accumulator (use
pde_init * * if you want to wipe).

---- INIT ----

Return all (Mat, Sol) keys currently in the accumulator.

---- inspection helpers ----

---- SET_SELF (own bulk contribution, idempotent across rebuild passes) ----

Rotated cubic stiffness for an arbitrary Miller orientation.

Usage:
  set cij [set_aniso_elastic C11=... C12=... C44=... Miller=(hkl)<uvw>]

Args:
  C11, C12, C44 — cubic stiffness constants in crystal frame (dynes/cm^2 or Pa)
  Miller        — orientation in (hkl)<uvw> notation; default (001)<100>

Returns a 15-element list (see __pack_aniso_result above) that the
cij_get/cij_atensor helpers consume.

Rotated transverse-isotropic stiffness from engineering constants.

Usage:
  set cij [set_transverse_iso_elastic E1=... E2=... v12=... v23=... G12=...]

Args:
  E1, E2 — Young's moduli (1 = out of plane, 2 = in plane)
  v12    — Poisson's ratio for stress-1 / strain-2 coupling
  v23    — Poisson's ratio within the isotropic plane
  G12    — Shear modulus in plane containing the 1-axis
  Miller — orientation (hkl)<uvw>; default (001)<100>

Returns a 12-element list (no 2D-RHS compliance terms — transverse-iso
decks don't use those entries):
  c00 c01 c02 c10 c11 c12 c20 c21 c22 c33 c44 c55

stress — elastic Newton solve.  Subcommands:
  stress pull          pull-mode elastic equation setup
  stress [calcstress]  Newton solve + (default) materialise TSXX..TSZX
  stress !calcstress   skip the tensor materialisation
Dispatches the actual solve through `solve stress`, which calls
RunStressSolve in src/device/stress.cc.

Declare common stress-deck variant materials with their canonical parents.
Idempotent.  Each variant's parent base is initialized first via its
`::ElasticInit` (which auto-declares its own parent recursively, ending
at BaseMat).

Variants are no longer listed here — each variant declares itself via
`elastic_variant <Variant> <Parent>` in its parent's ElasticEquations.tcl
(e.g., STIox / ILDox / HiK in Oxide/ElasticEquations.tcl).  The full
`mater list`-style registry lives at `::Elastic::Variants`, populated
at file-source time when stress_pull's pre-init loop calls each
`<base>::ElasticInit`.

Call this BEFORE `init inf=...` if the loaded structure references the
variants — otherwise the structure-file load will register the variants
without inheritance, and stress pull's dispatch loop can't resolve
them via `mater get.inherit`.

Scan Tcl's auto_index for `::<Mat>::ElasticInit` entries (the auto-load
triggers emitted by the elastic_base declarator).

stress pull — pull-mode elasticity setup.

Walks `mater list`, dispatches each material:

  (a) Material has a `::Models <Mat> Elasticity` entry → composer
      (`__compose_elasticity` in
      `TclLib/Models/StressCompose.tcl`) validates the chosen
      Anisotropic / Isotropic slice and pre-stamps the matparam
      keys (::<Mat>::Model, ::<Mat>::C11/12/44 OR
      ::<Mat>::YoungsModulus/PoissonRatio, optional
      ::<Mat>::ThermalAlpha) that the legacy `::ElasticEqns`
      dispatcher reads.
  (b) Material has no `::Models <Mat> Elasticity` entry →
      falls back to the legacy `namespace eval Mat { variable
      C11 ... }` declarations in
      `TclLib/Device/<Mat>/ElasticEquations.tcl`.

After the per-material dispatch, this proc initializes the strain
/ stress / displacement field surface and walks `mater list` to
emit per-region elasticity PDEs via `::ElasticEqns`.  `StressPackage`
is no longer called — its body is unreachable from `stress pull`.

Decks that still call `StressPackage` directly continue to work
until Phase G migrates them.  See `doc/BOTTOMUP.md` §14.

Surface diffusion-limited rate at a Mat/Side interface.  Uses Side's D0 +
Lspa and Mat's KinkSite.