LevenbergMarquardtSettings

class pyarts3.arts.LevenbergMarquardtSettings(*args, **kwargs)

Named Levenberg–Marquardt damping controls for OEM.

Pass this object as ws.oemCalc(settings=OptimalEstimationSettings(method="lm", lm=settings)). The same settings apply to lm_cg and the ml/ml_cg aliases. Defaults provide an explicit starting configuration, with ordinary convergence enabled only once damping reaches zero. They do not guarantee convergence for every forward model. Use describe() to inspect their meaning and the current values.

Construction and every field assignment validate all controls. Invalid edits raise an error naming the setting and preserve the previous configuration. When increasing initial_damping beyond the current maximum, raise maximum_damping first. To change several controls at once, construct a replacement object with their named arguments. validate() checks the settings again. OEM accepts this type directly and validates it before a Levenberg-Marquardt retrieval. Python also accepts a six-value sequence directly or through the constructor. Its order is initial_damping, decrease_factor, increase_factor, maximum_damping, damping_threshold, convergence_damping_limit. This input shorthand does not add a vector conversion to the C++ type. See Configuring an optimal-estimation retrieval for tuning guidance.

Overview

Method	`describe()`	Explain the current values, their effects, and tuning tradeoffs.
Method	`readxml()`	Read variable from file.
Method	`savexml()`	Saves variable to file.
Method	`validate()`	Check the current named values and their coupled constraints.
Static Method	`fromxml()`	Create variable from file.
`float`	`convergence_damping_limit`	Largest updated damping at which the ordinary `stop_dx` test is enabled.
`float`	`damping_threshold`	Positive restart damping and threshold for returning to Gauss–Newton.
`float`	`decrease_factor`	Divisor used when the local model warrants decreasing damping.
`float`	`increase_factor`	Multiplier used when an unsuccessful trial requires more damping.
`float`	`initial_damping`	Initial damping gamma. Larger values restrain initial steps more strongly.
`float`	`maximum_damping`	Upper damping limit. Must be finite and positive, and no smaller than
`int`	`maximum_trials`	Maximum linear-solve trials per outer iteration, including stationarity checks.
Operator	`__eq__()`	Return self==value.
Operator	`__format__()`	Default object formatter.
Operator	`__ge__()`	Return self>=value.
Operator	`__gt__()`	Return self>value.
Operator	`__hash__()`	Return hash(self).
Operator	`__init__()`	Overloaded function.
Operator	`__le__()`	Return self<=value.
Operator	`__lt__()`	Return self<value.
Operator	`__ne__()`	Return self!=value.
Operator	`__repr__()`	`__repr__(self) -> str`
Operator	`__str__()`	`__str__(self) -> str`

Constructors

__init__(self, arg: LevenbergMarquardtSettings) → None

__init__(self, values: Sequence[float]) → None

__init__(self, *, initial_damping: float = 10.0, decrease_factor: float = 2.0, increase_factor: float = 2.0, maximum_damping: float = 100.0, damping_threshold: float = 1.0, convergence_damping_limit: float = 0.0, maximum_trials: int = 100) → None

Overloaded function.

__init__(self, arg: pyarts3.arts.LevenbergMarquardtSettings) -> None
__init__(self, values: collections.abc.Sequence[float]) -> None
__init__(self, *, initial_damping: float = 10.0, decrease_factor: float = 2.0, increase_factor: float = 2.0, maximum_damping: float = 100.0, damping_threshold: float = 1.0, convergence_damping_limit: float = 0.0, maximum_trials: int = 100) -> None

Construct validated damping controls using named arguments.

Methods

describe(self) → str: Explain the current values, their effects, and tuning tradeoffs.

readxml(self, file: str) → str

Read variable from file.

Parameters:: file (str) – A file that can be read.
Raises:: RuntimeError – For any failure to read.
Returns:: file – The file path found (may differ from input due to environment variables).
Return type:: str

savexml(self, file: str, type: str = 'ascii', clobber: bool = True) → str

Saves variable to file.

Parameters:

file (str) – The path to which the file is written. Note that several of the options might modify the name or write more files.
type (str, optional) – Type of file to save. See FileType for options. Defaults is “ascii”.
clobber (bool, optional) – Overwrite existing files or add new file with modified name? Defaults is True.

Raises:

RuntimeError – For any failure to write.

Returns:

file – The file saved. May differ from input.

Return type:

str

validate(self) → None: Check the current named values and their coupled constraints.

Static Methods

fromxml(file: str) → LevenbergMarquardtSettings

Create variable from file.

Parameters:: file (str) – A file that can be read
Raises:: RuntimeError – For any failure to read.

Attributes

convergence_damping_limit: float: Largest updated damping at which the ordinary stop_dx test is enabled. Must be finite and nonnegative. Zero waits until damping reaches zero. A positive value permits convergence while damping still restrains steps, which can hide a remaining distance to the minimum.

damping_threshold: float: Positive restart damping and threshold for returning to Gauss–Newton. A proposed decrease below this value sets damping to zero. A rejected trial below this value restarts here. Must be finite and no greater than maximum_damping.

decrease_factor: float: Divisor used when the local model warrants decreasing damping. Must be finite and greater than one. A larger value releases damping faster. Not every accepted step causes a decrease.

increase_factor: float: Multiplier used when an unsuccessful trial requires more damping. Must be finite and greater than one. A larger value increases damping faster; an increase from zero first restarts at damping_threshold.

initial_damping: float: Initial damping gamma. Larger values restrain initial steps more strongly. Must be finite, nonnegative, and no greater than maximum_damping. Zero starts with a Gauss–Newton step.

maximum_damping: float: Upper damping limit. Must be finite and positive, and no smaller than initial_damping or damping_threshold. Failure to obtain an acceptable step at this value stops the retrieval. Check the forward model, Jacobian, and covariance scales before raising it.

maximum_trials: int: Maximum linear-solve trials per outer iteration, including stationarity checks.

Operators

__eq__(value, /): Return self==value.

__format__(format_spec, /)

Default object formatter.

Return str(self) if format_spec is empty. Raise TypeError otherwise.

__ge__(value, /): Return self>=value.

__gt__(value, /): Return self>value.

__hash__(): Return hash(self).

__init__(self, arg: LevenbergMarquardtSettings) → None

__init__(self, values: Sequence[float]) → None

__init__(self, *, initial_damping: float = 10.0, decrease_factor: float = 2.0, increase_factor: float = 2.0, maximum_damping: float = 100.0, damping_threshold: float = 1.0, convergence_damping_limit: float = 0.0, maximum_trials: int = 100) → None

Overloaded function.

__init__(self, arg: pyarts3.arts.LevenbergMarquardtSettings) -> None
__init__(self, values: collections.abc.Sequence[float]) -> None
__init__(self, *, initial_damping: float = 10.0, decrease_factor: float = 2.0, increase_factor: float = 2.0, maximum_damping: float = 100.0, damping_threshold: float = 1.0, convergence_damping_limit: float = 0.0, maximum_trials: int = 100) -> None

Construct validated damping controls using named arguments.

__le__(value, /): Return self<=value.

__lt__(value, /): Return self<value.

__ne__(value, /): Return self!=value.

__repr__(self) → str

__str__(self) → str