Classes
class	Dimension

class	Moves

class	NeighbourhoodError

class	Study

Functions
bytes	name_key (str name)

Dimension	dimension (str name, Any spec)

Study	prepare (Any sources, *Any space=None)

list	top_ids (Any sources, int k, *Any space=None)

dict	neighbourhood (Any sources, *Any centres, Any band, Any fraction=None, Any ratio=None, Any pair_k, Any max_work=None, Any space=None)

Variables
str	CONTRACT = "pineforge-hpo-neighbourhood/v1"

tuple	CODES

str	SCORED_OK = "scored_ok"

str	SCORED_INFEASIBLE = "scored_infeasible"

str	UNSCORABLE = "unscorable"

str	NEVER_EVALUATED = "never_evaluated"

tuple	CLASSES = (SCORED_OK, SCORED_INFEASIBLE, UNSCORABLE, NEVER_EVALUATED)

tuple	INTERPRETATION

Detailed Description

Neighbourhood stability of finished trials, read after the fact (version 1).

A candidate's neighbours are the parameter vectors one move away from it on a
single dimension: one lattice step, the other values, a fraction of the range
or a ratio, by the kind of the dimension. The module looks the neighbours up in
the rows it is given and reports how many of them score near the best row. It
evaluates nothing and starts nothing: a neighbour that has no row is returned
as a missing vector, and the caller may evaluate it and call again.

Rows are read by ``_rows`` and every row is checked against the recorded space.
Every refusal is a ``NeighbourhoodError`` with a module-local code and no
number. The result document is a pure function of the rows, the space, the
centres and the caller's rules: any row order gives the same bytes when it is
written as JSON with sorted keys. See ``docs/neighbourhood.md``.

Function Documentation

◆ dimension()

Dimension pineforge_hpo.neighbourhood.dimension	(	str	name,
		Any	spec
	)

Build the dimension called ``name`` from its recorded-space entry.

The entry is checked the way the study spec checks a dimension: integer
bounds and a positive integer step with ``low <= high``; real bounds with an
optional positive step; a log dimension has positive bounds, and a log
integer step 1 while a log real has no step; a stepped real must have at
most 2^53 ordinals. A dimension with exactly one legal value is constant.
A categorical keeps the first of equal choices. Anything else raises
``NeighbourhoodError("neighbourhood_input_invalid")``.

Definition at line 362 of file neighbourhood.py.

◆ name_key()

bytes pineforge_hpo.neighbourhood.name_key ( str name )

Sort key of a dimension name: its UTF-8 bytes (byte-wise name order).

Definition at line 160 of file neighbourhood.py.

◆ neighbourhood()

dict pineforge_hpo.neighbourhood.neighbourhood	(	Any	sources,
		*Any	centres,
		Any	band,
		Any	fraction = `None`,
		Any	ratio = `None`,
		Any	pair_k,
		Any	max_work = `None`,
		Any	space = `None`
	)

Describe the neighbourhoods of the given centres from finished rows.

``sources`` is a non-empty list; an item is a path to a complete result JSON
or a rows JSONL, a parsed result, or a parsed list of rows, and its position
in the list is its source index. ``centres`` is a list of (source, trial_id)
pairs, each a row with status ok (``top_ids`` returns such a list). ``band``
is ``{"mode": "absolute" | "relative", "value": v}``: a scored ok neighbour
is near the best iff its gap to the best ok objective is at most ``v`` or
``v`` times the absolute best. ``fraction`` (continuous reals) and ``ratio``
(log dimensions) are needed only when a varying dimension uses them.
``pair_k`` must be passed: it has no default, and None refuses with
``neighbourhood_parameter_missing``. That many pair maps per centre are
built from the pairs with the most not-near neighbours, and an explicit 0
builds none. ``max_work`` bounds the rows plus the lookups. ``space`` is
used only when no row or result records one. No default exists for the
band, the fraction, the ratio, ``pair_k`` or ``max_work``.

The result is a JSON-ready dict (see ``docs/neighbourhood.md``). Refusals
raise ``NeighbourhoodError`` with one of ``CODES`` and, when several defects
exist, report the first in this order: caller parameters, reading the
sources, space and direction, context, dimensions, rows against the space,
duplicate conflicts, no ok row, no varying dimension, missing fraction or
ratio, a relative band at a zero reference, centres, work above
``max_work``.

Definition at line 991 of file neighbourhood.py.

References pineforge_hpo.neighbourhood.prepare().

◆ prepare()

Study pineforge_hpo.neighbourhood.prepare	(	Any	sources,
		*Any	space = `None`
	)

Read the sources and index their rows; see ``neighbourhood`` for refusals.

``sources`` is a non-empty list; an item is a path to a complete result JSON
or a rows JSONL, a parsed result, or a parsed list of rows. The position in
the list is the source index. ``space`` is a recorded-space dict or a
``StudySpec`` and is used only when no row or result records its space.

Definition at line 694 of file neighbourhood.py.

Referenced by pineforge_hpo.neighbourhood.neighbourhood(), and pineforge_hpo.neighbourhood.top_ids().

◆ top_ids()

list pineforge_hpo.neighbourhood.top_ids	(	Any	sources,
		int	k,
		*Any	space = `None`
	)

The (source, trial_id) of the ``k`` best distinct parameter vectors.

Only rows with status ok count. A vector is represented by its lowest
(source, trial_id); best first, ties by the lower (source, trial_id). Fewer
than ``k`` are returned when fewer vectors have an ok row. The sources are
read and refused exactly as in ``neighbourhood``.

Definition at line 717 of file neighbourhood.py.

References pineforge_hpo.neighbourhood.prepare().

Variable Documentation

◆ CLASSES

tuple pineforge_hpo.neighbourhood.CLASSES = (SCORED_OK, SCORED_INFEASIBLE, UNSCORABLE, NEVER_EVALUATED)

Definition at line 79 of file neighbourhood.py.

◆ CODES

tuple pineforge_hpo.neighbourhood.CODES

Initial value:

=  (
    "neighbourhood_input_invalid",
    "neighbourhood_rows_incomplete",
    "neighbourhood_space_missing",
    "neighbourhood_space_mismatch",
    "neighbourhood_context_mismatch",
    "neighbourhood_parameter_missing",
    "neighbourhood_parameter_invalid",
    "neighbourhood_band_degenerate",
    "neighbourhood_centre_invalid",
    "neighbourhood_no_varying_dimension",
    "neighbourhood_no_feasible_rows",
    "neighbourhood_duplicate_conflict",
    "neighbourhood_resource_exceeded",
)

Definition at line 59 of file neighbourhood.py.

◆ CONTRACT

str pineforge_hpo.neighbourhood.CONTRACT = "pineforge-hpo-neighbourhood/v1"

Definition at line 57 of file neighbourhood.py.

◆ INTERPRETATION

tuple pineforge_hpo.neighbourhood.INTERPRETATION

Initial value:

=  (
    "This describes the trials that were supplied and nothing else. "
    "It states no significance, confidence or probability. "
    "A neighbour that was never evaluated is not imputed, and nothing is said "
    "about it. "
    "The reference value is the best of many trials, so it is optimistic. "
    "With an adaptive sampler the neighbours that exist are not a random draw: "
    "the share near the best describes its stated neighbourhood only when "
    "coverage is 1. "
    "Every number is in-sample. "
    "Constraints, relations between parameters and whether two runs used the "
    "same data are not checked."
)

Definition at line 81 of file neighbourhood.py.

◆ NEVER_EVALUATED

str pineforge_hpo.neighbourhood.NEVER_EVALUATED = "never_evaluated"

Definition at line 78 of file neighbourhood.py.

◆ SCORED_INFEASIBLE

str pineforge_hpo.neighbourhood.SCORED_INFEASIBLE = "scored_infeasible"

Definition at line 76 of file neighbourhood.py.

◆ SCORED_OK

str pineforge_hpo.neighbourhood.SCORED_OK = "scored_ok"

Definition at line 75 of file neighbourhood.py.

◆ UNSCORABLE

str pineforge_hpo.neighbourhood.UNSCORABLE = "unscorable"

Definition at line 77 of file neighbourhood.py.

Classes

Functions

Variables