Etching

Etch rate modeling for track etching simulations.

Implements monotonic etch rate functions V(dose) over wide dose ranges.

class tracketch.etching.etch_rate_model.EtchRateModel(anchor_doses_Gy: ndarray | list[float] = array([1.00000000e+01, 6.30957344e+02, 3.98107171e+04, 2.51188643e+06, 1.58489319e+08, 1.00000000e+10]), V_bulk_um_h: float = 1.73, V_max_um_h: float | None = None, V_max_uncertainty_um_h: float | None = None, anchor_velocities_um_h: ndarray | list[float] | None = None, anchor_velocity_uncertainties_um_h: ndarray | list[float] | None = None, name: str | None = None, extrapolation_mode: str = 'pchip', debris_alpha: float | None = None, debris_beta: float = 1.0)[source]

Bases: object

LOW_DOSE_ANCHOR_GY: float = 0.001

summary() → str[source]: Return a compact human-readable summary of model settings and ranges.

update_debris_params(alpha: float | None, beta: float | None = None) → None[source]

Update debris-damping parameters.

Parameters:

alpha (float or None) – Characteristic aspect-ratio scale. None disables damping.
beta (float or None) – Transition steepness. None keeps current value.

property debris_damping_enabled: bool: Whether debris damping is active.

is_monotonic(num_points: int = 256) → bool[source]: Check monotonic non-decreasing behavior of v(d) on a dense log-dose grid.

eval(dose_Gy: float | ndarray) → float | ndarray[source]

Evaluate etch rate at given dose(s).

Parameters:: dose_Gy (float or array-like) – Dose in Gy.
Returns:: V_um_h – Etch rate in um/hour Returns scalar if input is scalar, array if input is array Returns V_bulk_um_h for NaN inputs Always >= V_bulk_um_h (physically consistent)
Return type:: float or ndarray

eval_uncertainty_band(dose_Gy: ndarray, n_sigma: float = 1.0, max_sigma_log10: float = 0.5) → tuple[ndarray, ndarray] | None[source]

Return lower and upper 1-sigma etch-rate bands at the given doses.

Converts per-anchor velocity uncertainties to log10-velocity space, interpolates them onto dose_Gy with PCHIP (in log-dose space), and applies the band symmetrically around eval(dose_Gy) in log10 space. Results are clipped to [V_bulk, V_max].

Parameters:

dose_Gy (array-like) – Dose values at which to evaluate the band.
n_sigma (float) – Number of standard deviations for the band width (default 1).
max_sigma_log10 (float) – Cap on interpolated sigma in log10-velocity units (default 0.5, i.e. ~factor-of-3 per sigma) to suppress artefacts from poorly-constrained high-dose anchors.

Returns:

tuple of (lower, upper) ndarrays, or None if no anchor uncertainties
are set on the model.

update_velocities(new_velocities_um_h: ndarray | list[float]) → None[source]

Update anchor velocities and recreate spline.

Accepts absolute velocities, validates them for monotonicity, and converts to relative increments internally.

Useful during optimization loops.

Parameters:: new_velocities_um_h (array-like) – New absolute velocity values for anchor points [um/hour]
Raises:: ValueError – If new velocities violate monotonicity

get_increments() → ndarray[source]

Get relative velocity increments (for optimization).

Returns:: increments – Relative increments [um/hour], all >= 0
Return type:: np.ndarray

get_log_velocity_increments() → ndarray[source]

Get monotonic increments in log10(velocity) space.

Defines:: u_i = log10(v_i) delta_u_0 = u_0 - log10(V_bulk_um_h) delta_u_i = u_i - u_{i-1} for i >= 1

Since anchor velocities are monotonic and >= V_bulk_um_h, all returned increments are guaranteed to be >= 0.

Returns:: Non-negative increments in log10(velocity) space.
Return type:: np.ndarray

get_log_doses() → ndarray[source]

Get log10 of dose anchors (for optimization in log-space).

Returns:: log_doses – log10 of anchor doses [dimensionless]
Return type:: np.ndarray

update_dose_anchors(anchor_doses_Gy: ndarray | list[float]) → None[source]

Update dose anchor positions and recreate spline.

Validates that doses are strictly increasing.

Parameters:: anchor_doses_Gy (array-like) – New dose anchor points [Gy]. Must be strictly increasing.
Raises:: ValueError – If doses not strictly increasing or length doesn’t match velocities

update_from_increments(increments_um_h: ndarray | list[float]) → None[source]

Update velocities from relative increments (for optimization).

This is the recommended approach for optimization: optimize the increments directly to guarantee monotonicity by construction.

Parameters:: increments_um_h (array-like) – Relative increments [um/hour]. Must be all >= 0 and have same length as anchor points.
Raises:: ValueError – If increments are negative or length doesn’t match If resulting velocities would be < V_bulk_um_h

update_from_log_velocity_increments(log_velocity_increments: ndarray | list[float]) → None[source]

Update anchor velocities from non-negative log10(velocity) increments.

This parameterization is robust for wide dynamic ranges because optimization steps act multiplicatively on velocity.

Parameters:: log_velocity_increments (array-like) – Increments in log10(velocity) space. Must all be >= 0 and have the same length as anchor points.

static log_increments_to_linear(log_increments: ndarray | list[float], epsilon: float = 1e-06) → ndarray[source]

Convert log-space increments to linear (for unconstrained optimization).

For optimization, parameterize as: log_increments = log(increments + epsilon) This ensures increments are always positive without constraints.

Parameters:

log_increments (array-like) – Log-transformed increments (can be any real number)
epsilon (float, optional) – Small offset to ensure positivity (default: 1e-6)

Returns:

increments – Linear increments, all > epsilon

Return type:

np.ndarray

static linear_increments_to_log(increments: ndarray | list[float], epsilon: float = 1e-06) → ndarray[source]

Convert linear increments to log-space (for unconstrained optimization).

Inverse of log_increments_to_linear.

Parameters:

increments (array-like) – Linear increments (must all be > -epsilon)
epsilon (float, optional) – Small offset used during forward conversion (default: 1e-6)

Returns:

log_increments – Log-transformed increments

Return type:

np.ndarray

static log_velocity_increments_to_linear(optimization_parameters: ndarray | list[float], epsilon: float = 1e-12) → ndarray[source]: Map unconstrained optimizer parameters to positive log-velocity increments.

static linear_log_velocity_increments_to_optimization(log_velocity_increments: ndarray | list[float], epsilon: float = 1e-12) → ndarray[source]: Map positive log-velocity increments to unconstrained optimizer parameters.

plot(dose_range: tuple[float, float] = (1e-06, 10000000000000.0), n_points: int = 500, show_anchors: bool = True, show_v_bulk: bool = True, show_uncertainty_band: bool = True) → tuple[Figure, Axes][source]

Plot the etch rate function.

Parameters:

dose_range (tuple, optional) – (min_dose, max_dose) in Gy for x-axis
n_points (int, optional) – Number of evaluation points
show_anchors (bool, optional) – Whether to show anchor points
show_v_bulk (bool, optional) – Whether to show V_bulk_um_h reference line
show_uncertainty_band (bool, optional) – Whether to show uncertainty band if anchor uncertainties are available

Returns:

fig, ax

Return type:

matplotlib figure and axes

save_to_json(filepath: str) → None[source]

Save the etch rate model to a JSON file.

Parameters:: filepath (str) – Path to the output JSON file

Examples

>>> model.save_to_json("my_model.json")

classmethod load_from_json(filepath: str, verbose: bool = False) → EtchRateModel[source]

Load an etch rate model from a JSON file.

Parameters:: filepath (str) – Path to the JSON file
Returns:: The loaded model
Return type:: EtchRateModel

Examples

>>> model = EtchRateModel.load_from_json("my_model.json")

Etch-rate model persistence and default-model factory.

Provides save_etchrate_model(), load_etchrate_model(), and a convenience factory default_etch_rate_model().

tracketch.etching.etch_rate_model_io.default_etch_rate_model(n_anchors: int = 15, bulk_rate_um_h: float = 1.73) → EtchRateModel[source]

Generate a generic etch-rate model initialised from Doerschel data.

Parameters:

n_anchors (int) – Number of fine-resolution anchor points in the high-dose region.
bulk_rate_um_h (float) – Bulk etch rate in um/hr.

Return type:

tracketch.etching.etch_rate_model.EtchRateModel

tracketch.etching.etch_rate_model_io.get_model_path(model_name: str) → Path[source]

Get the full path to a model file based on config.

Parameters:: model_name (str) – The model identifier (e.g., ‘Doerschel_etching’)
Returns:: Full path to the model file
Return type:: Path

Examples

>>> path = get_model_path('Doerschel_etching')

tracketch.etching.etch_rate_model_io.save_etchrate_model(model: EtchRateModel, model_name: str) → None[source]

Save a model using the configured path.

Parameters:

model (tracketch.etching.etch_rate_model.EtchRateModel) – The model to save
model_name (str) – The model identifier (e.g., ‘Doerschel_etching’)

Examples

>>> save_etchrate_model(my_model, 'my_custom_model')

tracketch.etching.etch_rate_model_io.load_etchrate_model(model_name: str) → EtchRateModel[source]

Load a model using the configured path.

Parameters:: model_name (str) – The model identifier (e.g., ‘Doerschel_etching’)
Returns:: The loaded model
Return type:: tracketch.etching.etch_rate_model.EtchRateModel

Examples

>>> model = load_etchrate_model('Doerschel_etching')