Skip to content

Approaches Submodule

SRToolkit.approaches

This module contains implementations of symbolic regression approaches. Class SR_approach is the base class for all symbolic regression approaches.

Modules:

Name Description
sr_approach

The base class for all symbolic regression approaches.
ProGED

The ProGED approach - Probabilistic grammar-based equation discovery.

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 
22
23
24
25
26
27
28
29
30
31
32
33
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 
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
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 
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
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 
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
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 
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
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 
146
147
148
149
150
151
152
153
154
155
156
157
158
159
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