SR Approach

SRToolkit.approaches.sr_approach

This module contains the SR_approach class, which is the base class for all symbolic regression approaches.

SR_approach

SR_approach(name: str)

The base class for all symbolic regression approaches. Any symbolic regression approach should inherit from this class.

If the approach requires pretraining on an external corpus, this should be done inside __init__. The approach is responsible for defining what corpus it expects and how to load it.

Parameters:

Name	Type	Description	Default
name	str	The name of the approach.	required

Source code in SRToolkit/approaches/sr_approach.py

def __init__(self, name: str):
    """
    The base class for all symbolic regression approaches. Any symbolic regression approach should inherit from
    this class.

    If the approach requires pretraining on an external corpus, this should be done inside ``__init__``.
    The approach is responsible for defining what corpus it expects and how to load it.

    Args:
        name: The name of the approach.
    """
    self.name = name

adaptation_scope property

adaptation_scope: str

Controls when adapt() is called by the framework, and whether save_adapted_state() / load_adapted_state() are used.

• "never": adapt() is never called (default). save_adapted_state() and load_adapted_state() do not need to be implemented.
• "once": adapt() is called once; the framework caches the result via save_adapted_state() and restores it via load_adapted_state() on subsequent experiments with the same library. Both methods must be implemented when this scope is used.
• "experiment": adapt() is called before every search(). save_adapted_state() is called only if save_adapted_model is also True.

For neural approaches, we recommend you save weights to disk with save_adapted_state() and return an identifier (e.g. a file path). load_adapted_state() receives that identifier and loads the weights from the disk, keeping the in-memory cache small.

Returns:

Type	Description
str	One of "never", "once", or "experiment".

save_adapted_model property

save_adapted_model: bool

Whether the framework should call save_adapted_state() when adaptation_scope is "experiment". Ignored for "never" and "once" scopes (the latter always saves). Default is False.

Returns:

Type	Description
bool	True if the adapted model should be saved after each adaptation.

prepare

prepare() -> None

Reset the approach's per-experiment state in preparation for a new run.

Called by the framework before adapt() and search() for every experiment, so any state accumulated during a previous run is cleared before the next one starts.

Three cases:

• Stateless (e.g. random sampling): implement as pass.
• Stateful search (e.g. GP): reset the population or any other mutable search state to its initial configuration.
• Pretrained weights + per-run search state (e.g. neural): reset only the search state; leave pretrained weights untouched.

Source code in SRToolkit/approaches/sr_approach.py

def prepare(self) -> None:
    """
    Reset the approach's per-experiment state in preparation for a new run.

    Called by the framework before ``adapt()`` and ``search()`` for every
    experiment, so any state accumulated during a previous run is cleared
    before the next one starts.

    Three cases:

    - **Stateless** (e.g. random sampling): implement as ``pass``.
    - **Stateful search** (e.g. GP): reset the population or any other
      mutable search state to its initial configuration.
    - **Pretrained weights + per-run search state** (e.g. neural): reset
      only the search state; leave pretrained weights untouched.
    """
    raise NotImplementedError

adapt

adapt(X: ndarray, symbol_library: SymbolLibrary) -> None

Adapt the approach to the target dataset's input space and symbols in the symbol library.

Called by the framework after prepare() and before search(), according to adaptation_scope. This method must NOT access target values (y) or evaluate expressions (e.g. by calling sr_evaluator.evaluate_expr()) during adaptation — only the points from the domain and the symbol library may be used.

Parameters:

Name	Type	Description	Default
X	ndarray	input variables from the domain, shape (n_samples, n_variables).	required
symbol_library	SymbolLibrary	The symbol library defining the available symbols/tokens.	required

Source code in SRToolkit/approaches/sr_approach.py

def adapt(self, X: np.ndarray, symbol_library: SymbolLibrary) -> None:
    """
    Adapt the approach to the target dataset's input space and symbols in the symbol library.

    Called by the framework after ``prepare()`` and before ``search()``, according
    to ``adaptation_scope``. This method must NOT access target values (y) or evaluate
    expressions (e.g. by calling ``sr_evaluator.evaluate_expr()``) during adaptation —
    only the points from the domain and the symbol library may be used.

    Args:
        X: input variables from the domain, shape ``(n_samples, n_variables)``.
        symbol_library: The symbol library defining the available symbols/tokens.
    """
    raise NotImplementedError

search

search(sr_evaluator: SR_evaluator, seed: Optional[int] = None)

Run the symbolic regression search.

Implementations must call sr_evaluator.evaluate_expr(expr) to score candidate expressions. The evaluator accumulates all results internally; do not call sr_evaluator.get_results() — that is handled by the framework after search finishes.

Stop conditions to respect

• sr_evaluator.total_evaluations >= sr_evaluator.max_evaluations (when max_evaluations > 0)
• The current best error has dropped below sr_evaluator.success_threshold

The symbol library is available in sr_evaluator.symbol_library.

Parameters:

Name	Type	Description	Default
sr_evaluator	SR_evaluator	Evaluator used to score expressions. All results are stored inside this object.	required
seed	Optional[int]	Optional random seed for reproducible expression generation.	None

Returns:

Type	Description
	None

Source code in SRToolkit/approaches/sr_approach.py

def search(self, sr_evaluator: SR_evaluator, seed: Optional[int] = None):
    """
    Run the symbolic regression search.

    Implementations must call ``sr_evaluator.evaluate_expr(expr)`` to score
    candidate expressions. The evaluator accumulates all results internally;
    do not call ``sr_evaluator.get_results()`` — that is handled by the
    framework after ``search`` finishes.

    Stop conditions to respect:
        - ``sr_evaluator.total_evaluations >= sr_evaluator.max_evaluations``
          (when ``max_evaluations > 0``)
        - The current best error has dropped below ``sr_evaluator.success_threshold``

    The symbol library is available in ``sr_evaluator.symbol_library``.

    Args:
        sr_evaluator: Evaluator used to score expressions. All results are
            stored inside this object.
        seed: Optional random seed for reproducible expression generation.

    Returns:
        None
    """
    raise NotImplementedError

save_adapted_state

save_adapted_state() -> Any

Saves the adapted model/approach and returns the saved state.

For neural approaches we suggest you save the model's weights to disk (e.g. via torch.save) and return the file path. The returned value is stored in memory by the framework and passed back to load_adapted_state() when the cached state is needed.

Must be implemented when adaptation_scope == "symbol_library", or when adaptation_scope == "experiment" and save_adapted_model is True.

Returns:

Type	Description
Any	The saved state (e.g., a file path or the model).

Source code in SRToolkit/approaches/sr_approach.py

def save_adapted_state(self) -> Any:
    """
    Saves the adapted model/approach and returns the saved state.

    For neural approaches we suggest you save the model's weights to disk (e.g. via
    ``torch.save``) and return the file path. The returned value is stored
    in memory by the framework and passed back to ``load_adapted_state()``
    when the cached state is needed.

    Must be implemented when ``adaptation_scope == "symbol_library"``, or
    when ``adaptation_scope == "experiment"`` and ``save_adapted_model`` is
    ``True``.

    Returns:
        The saved state (e.g., a file path or the model).
    """
    raise NotImplementedError

load_adapted_state

load_adapted_state(state: Any) -> None

Restore the previously saved state.

For neural approaches we suggest that this function loads weights from the disk using the identifier returned by save_adapted_state() (e.g. a file path passed to torch.load).

Must be implemented when adaptation_scope == "symbol_library"

Parameters:

Name	Type	Description	Default
state	Any	The identifier previously returned by save_adapted_state().	required

Source code in SRToolkit/approaches/sr_approach.py

def load_adapted_state(self, state: Any) -> None:
    """
    Restore the previously saved state.

    For neural approaches we suggest that this function loads weights from the disk
    using the identifier returned by ``save_adapted_state()`` (e.g. a file path
    passed to ``torch.load``).

    Must be implemented when ``adaptation_scope == "symbol_library"``

    Args:
        state: The identifier previously returned by ``save_adapted_state()``.
    """
    raise NotImplementedError