fit.result¶

Result of optimization.

OptimizationResult ¶

OptimizationResult(
    parameters,
    fits,
    trajectories,
    sid=None,
    opid=None,
    settings=None,
    units=None,
    provenance=None,
)

Bases: ObjectJSONEncoder

Result of optimization problem.

Initialize optimization result.

Provides access to the FitParameters, the individual fits, and the trajectories of the fits. The settings and the id of the problem are stored with the result, a report of the fit needs them.

Parameters:

Name	Type	Description	Default
`parameters`	`Iterable[FitParameter]`	fit parameters of the optimization problem.	required
`fits`	`list[OptimizeResult]`	results of the single optimizations.	required
`trajectories`	`list[list[float]]`	cost of every step of the single optimizations.	required
`sid`	`str \| None`	identifier of the result, created from the time by default.	`None`
`opid`	`str \| None`	id of the optimization problem the result belongs to.	`None`
`settings`	`FitSettings \| dict[str, Any] \| None`	settings the fit was run with.	`None`
`units`	`Mapping[str, str \| None] \| None`	the unit of every parameter in the units of pint by parameter id, see `OptimizationProblem.parameter_units`; the units of the parameters by default.	`None`
`provenance`	`FitProvenance \| dict[str, Any] \| None`	what the fit ran with (arguments, seeds, versions, git revision, checksums), `None` for a result of a fit which did not record it.	`None`

settings_stored `property` ¶

settings_stored

Settings the fit was run with.

Raises:

Type	Description
`ValueError`	if the result carries no settings, e.g., because it was created by hand.

size `property` ¶

size

Get number of optimization runs in result.

xopt `property` ¶

xopt

Numerical values of optimal parameters.

xopt_fit_parameters `property` ¶

xopt_fit_parameters

Optimal parameters as Fit parameters.

scales `property` ¶

scales

Get the scale the optimizer searched every parameter in.

It is the FitParameter.scale of a parameter and the parameter_scale of the settings, of the default settings for a result without them, for a parameter without one.

write_run `staticmethod` ¶

write_run(
    directory,
    parameters,
    fit,
    trajectory,
    sid,
    opid=None,
    settings=None,
    units=None,
    provenance=None,
)

Store a single optimization run as JSON.

The runs are stored while the fit runs, so a fit which is interrupted, times out or crashes leaves the runs which finished.

Parameters:

Name	Type	Description	Default
`directory`	`Path`	directory of the runs, created if it does not exist.	required
`parameters`	`Iterable[FitParameter]`	fit parameters of the problem.	required
`fit`	`OptimizeResult`	result of the single optimization.	required
`trajectory`	`list[float]`	trajectory of the single optimization.	required
`sid`	`str`	id of the run, the name of its file.	required
`opid`	`str \| None`	id of the optimization problem.	`None`
`settings`	`FitSettings \| None`	settings of the fit.	`None`
`units`	`Mapping[str, str \| None] \| None`	the units of pint of the parameters, see `__init__`.	`None`
`provenance`	`FitProvenance \| None`	what the fit ran with, every run carries it.	`None`

Returns:

Type	Description
`Path`	Path of the file the run was written to.

from_directory `staticmethod` ¶

from_directory(directory, sid=None)

Collect the optimization runs of a directory.

This is the counterpart of write_run: the runs a fit stored are read back and combined, which recovers the results of a fit which did not finish.

Parameters:

Name	Type	Description	Default
`directory`	`Path`	directory with the JSON files of the runs.	required
`sid`	`str \| None`	id of the combined result, the name of the directory by default.	`None`

Returns:

Type	Description
`OptimizationResult`	The combined result of all runs in the directory.

Raises:

Type	Description
`ValueError`	if the directory holds no run.

to_tsv ¶

to_tsv(path)

Store fit results as TSV, one line per run.

The columns named by the parameter ids are the fitted values, the columns x0.<pid> the start values of the run (. is no character of an id, so the names cannot collide). The vectors x and x0 of df_fits are not written as such, their text would span several lines and be rounded.

to_dict ¶

to_dict()

Convert to dictionary.

to_json ¶

to_json(path=None)

Store OptimizationResult as json.

Uses the to_dict method.

from_json `staticmethod` ¶

from_json(json_info)

Load OptimizationResult from Path or str.

:param json_info: :return:

parameter_set ¶

parameter_set(k=0, sid=None)

Get the parameters of a single optimization run.

The runs are ordered by increasing cost, so k=0 is the best fit.

Parameters:

Name	Type	Description	Default
`k`	`int`	index of the run in the results ordered by cost.	`0`
`sid`	`str \| None`	identifier of the set, `<result id>_<k>` by default.	`None`

Returns:

Type	Description
`ParameterSet`	The parameter set of the run.

Raises:

Type	Description
`IndexError`	if the result has no run `k`.

parameter_sets ¶

parameter_sets(size=1)

Get the parameters of the best optimization runs.

Parameters:

Name	Type	Description	Default
`size`	`int`	number of runs, ordered by increasing cost.	`1`

Returns:

Type	Description
`ParameterSets`	The parameter sets of the best runs.

combine `staticmethod` ¶

combine(opt_results)

Combine results from multiple parameter fitting experiments.

Raises:

Type	Description
`ValueError`	if no results are given or their parameter definitions, settings or units are incompatible.

process_traces `staticmethod` ¶

process_traces(trajectories)

Process the trajectories of the optimizations.

A trajectory is the cost of every step of a run, which is what the trace plot of a report shows.

Parameters:

Name	Type	Description	Default
`trajectories`	`list[list[float]]`	cost of every step, per run.	required

Returns:

Type	Description
`DataFrame`	DataFrame with the columns `run`, `step` and `cost`.

process_fits `staticmethod` ¶

process_fits(parameters, fits)

Process the optimization results, sorted by increasing cost.

report ¶

report(path=None, print_output=True, groups=None)

Report of optimization.

Parameters:

Name	Type	Description	Default
`path`	`Path \| None`	file the report is written to, none by default.	`None`
`print_output`	`bool`	print the report.	`True`
`groups`	`Mapping[str, Collection[str]] \| None`	the groups of elements which are reported as one, e.g. the arrays of a network, see `bound_warnings`. The optimal parameters are listed as one line per group.	`None`

fit_id ¶

fit_id(name=None)

Create the unique id of a fit from the time and a short hash.

The id is created when a fit starts and is the id of its optimization problem, of its result and of the directory of its report, so that everything a fit produces carries the same key and sorts by time.

Parameters:

Name	Type	Description	Default
`name`	`str \| None`	name the id is prefixed with, e.g., the name of the problem.	`None`

Returns:

Type	Description
`str`	`<name>_<date>_<time>__<hash>`, e.g. `PK_20260908_144538__ea1ff`.

bound_warnings ¶

bound_warnings(
    parameters, x, scales, rtol=0.05, groups=None
)

Warn about optimal parameters which ended up on their bounds.

A parameter on its bound means that the optimum is outside of the box in which the parameter was allowed to vary.

The distance to a bound is relative to the interval of the parameter, in the scale the optimizer searched the parameter in.

Parameters:

Name	Type	Description	Default
`parameters`	`list[FitParameter]`	fitted parameters with their bounds.	required
`x`	`ndarray`	optimal values of the parameters.	required
`scales`	`Sequence[ParameterScaleType]`	the scale of every parameter, see `OptimizationProblem.scales_initialized`.	required
`rtol`	`float`	relative distance to a bound which is reported.	`0.05`
`groups`	`Mapping[str, Collection[str]] \| None`	label of a group -> the ids of its elements, e.g. the arrays of a network with `ParameterGroup.ids`. A parameter belongs to the group which has the entity it writes (`FitParameter.entity_id`) as an element. The elements of a group are reported as one message which counts them, because a network has hundreds.	`None`

Returns:

Type	Description
`list[str]`	Messages for the parameters which are within `rtol` of one of their
`list[str]`	bounds, and one message per group with such elements.

fit.result¶

OptimizationResult ¶

settings_stored property ¶

size property ¶

xopt property ¶

xopt_fit_parameters property ¶

scales property ¶

write_run staticmethod ¶

from_directory staticmethod ¶

to_tsv ¶

to_dict ¶

to_json ¶

from_json staticmethod ¶

parameter_set ¶

parameter_sets ¶

combine staticmethod ¶

process_traces staticmethod ¶

process_fits staticmethod ¶

report ¶

fit_id ¶

bound_warnings ¶

settings_stored `property` ¶

size `property` ¶

xopt `property` ¶

xopt_fit_parameters `property` ¶

scales `property` ¶

write_run `staticmethod` ¶

from_directory `staticmethod` ¶

from_json `staticmethod` ¶

combine `staticmethod` ¶

process_traces `staticmethod` ¶

process_fits `staticmethod` ¶