# dso-org/deep-symbolic-optimization architecture

> Architecture diagram of the GitHub repository dso-org/deep-symbolic-optimization, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dso-org/deep-symbolic-optimization
- Repository: https://github.com/dso-org/deep-symbolic-optimization

## Overview

1. **What this repository is**
   - `dso` is a Python package for **Deep Symbolic Optimization**: it learns symbolic expressions or symbolic control policies by sampling programs from a learned policy and scoring them on a task.
   - The repo is split into a **core optimization engine** plus two first-class task families: **regression** and **control**.

2. **Primary runtime entry points**
   - `dso/run.py` is the command-line launcher described in the README.
   - `dso/core.py` contains the main `DeepSymbolicOptimizer` API used from Python.
   - `dso/train.py` likely owns the training loop orchestration, with `run.py` and the Python API both feeding into the same core path.

3. **Configuration is the main control surface**
   - Runs are driven by JSON configs under `dso/config/`, with shared defaults in `config_common.json` and task-specific defaults in `config_regression.json` and `config_control.json`.
   - Example configs in `config/examples/` show the two main task shapes: datasets for regression and Gym-style environments for control.
   - This means the architecture is **configuration-first**: the task, search space, priors, optimizer, logging, and optional GP/LM components are all selected before execution.

4. **Core symbolic representation and execution**
   - `program.py`, `library.py`, `functions.py`, and `execute.py` form the symbolic expression layer.
   - The **library** defines tokens/operators available to the search process; **program** represents a candidate expression; **execute** evaluates a program on task inputs.
   - `cyfunc.pyx` is a native acceleration path for function execution, indicating that expression evaluation is performance-sensitive.

5. **Search-space shaping: priors and constraints**
   - `prior.py` and `const.py` define search priors, constraints, and special tokens such as floating constants.
   - `memory.py`, `variance.py`, and `subroutines.py` support the optimizer’s statistical bookkeeping and helper operations.
   - In architecture terms, these components sit between the raw token library and the policy sampler, biasing which expressions get explored.

6. **Learning loop and state management**
   - The optimizer loop is centered around sampling candidate programs, evaluating reward, and updating the policy.
   - `checkpoint.py`, `train_stats.py`, `logeval.py`, and `tf_state_manager.py` handle persistence, metrics, and TensorFlow state restoration.
   - The data flow is: **config → task + library/prior → policy samples programs → task evaluates reward → optimizer updates parameters → logs/checkpoints written**.

7. **Policy model subsystem**
   - `policy/` contains the learned sequence model used to generate symbolic programs.
   - `policy/rnn_policy.py` suggests an RNN-based autoregressive policy, with `policy/policy.py` providing the shared policy interface.
   - This policy is the central generator in the system: it produces token sequences that become candidate expressions or policies.

8. **Policy optimization strategies**
   - `policy_optimizer/` contains interchangeable optimizers: `pg_policy_optimizer.py`, `ppo_policy_optimizer.py`, and `pqt_policy_optimizer.py`.
   - These correspond to different training objectives over sampled programs, including risk-seeking policy gradient, PPO, and priority-queue training.
   - Architecturally, this is a pluggable optimization boundary: the same program sampler and task evaluator can be paired with different update rules.

9. **Task abstraction**
   - `task/task.py` defines the task interface shared by all problem types.
   - The README and tree show a simple extension point for custom tasks, so tasks are not hard-wired into the optimizer; they supply reward evaluation, input/output structure, and any task-specific token additions.

10. **Regression subsystem**
   - `task/regression/` contains dataset loaders, benchmark definitions, and regression-specific utilities.
   - `dataset.py`, `regression.py`, `polyfit.py`, `sklearn.py`, and `mat_mult_benchmark.py` indicate support for CSV datasets, benchmark suites, and polynomial/linear sub-fitting inside expressions.
   - The regression task is centered on recovering mathematical expressions from data, with optional constant optimization and the `poly` token as a structured inner optimization.

11. **Control subsystem**
   - `task/control/` wraps symbolic policy search over reinforcement-learning environments.
   - `control.py`, `envs/`, `utils.py`, and `data/` show that this task includes custom environment adapters and pretrained anchor policies.
   - Important architectural boundary: for multi-action environments, the system can mix symbolic actions, fixed symbolic expressions, and anchor-policy outputs within one action specification.

12. **Optional hybrid search: genetic programming**
   - `gp/` contains a separate GP controller (`gp_controller.py`, `base.py`, `utils.py`) used for neural-guided genetic programming population seeding.
   - This is an **inner-loop optimizer** that can be enabled from config and runs alongside or inside the main neural-guided search process.
   - In diagrams, it should be shown as an optional branch that consumes task evaluations and produces candidate populations.

13. **Optional language-model prior**
   - `language_model/` contains a learned prior over token sequences, including a saved TensorFlow model checkpoint.
   - `language_model_prior.py` integrates that model into the search distribution, biasing program sampling toward patterns learned offline.
   - This is a distinct prior source, separate from handcrafted priors in `prior.py`.

14. **Testing, artifacts, and packaged assets**
   - `test/` contains unit tests for core program behavior, priors, checkpointing, and custom-task extension points.
   - The repo also ships benchmark data, pretrained control policies, and a saved language-model checkpoint, meaning the package is not purely code-driven; it depends on bundled artifacts for reproducible experiments.
   - The `setup.py` packaging and the TensorFlow-era saved models indicate the project is designed as an installable research framework with both library and experiment assets.

Main entry points: [`dso/dso/train.py`](https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/train.py) (Training loop), [`dso/dso/config/config_common.json`](https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/config/config_common.json) (Configs), [`dso/dso/task/task.py`](https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/task/task.py) (Task API), [`dso/dso/program.py`](https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/program.py) (Program)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_core["Core engine"]
  node_node_run["CLI run<br/>entrypoint<br/>[run.py]"]
  node_node_core["Optimizer API<br/>orchestrator<br/>[core.py]"]
  node_node_train["Training loop<br/>[train.py]"]
  node_node_program["Program<br/>symbolic IR<br/>[program.py]"]
  node_node_library[("Library<br/>token space<br/>[library.py]")]
  node_node_execute["Execute<br/>evaluator<br/>[execute.py]"]
  node_node_functions["Functions<br/>ops<br/>[functions.py]"]
  node_node_cyfunc{{"Native funcs<br/>accelerator<br/>[cyfunc.pyx]"}}
  node_node_prior["Priors<br/>search bias<br/>[prior.py]"]
  node_node_const["Constants<br/>token support<br/>[const.py]"]
  node_node_config["Configs<br/>configuration<br/>[config_common.json]"]
  node_node_checkpoint["State & logs<br/>persistence<br/>[checkpoint.py]"]
end

subgraph group_group_policy["Policy search"]
  node_node_policy["Policy model<br/>sequence model<br/>[policy.py]"]
  node_node_rnn["RNN policy<br/>autoregressive policy<br/>[rnn_policy.py]"]
  node_node_pg["PG optimizer<br/>update rule"]
  node_node_ppo["PPO optimizer<br/>update rule"]
  node_node_pqt["PQT optimizer<br/>update rule"]
end

subgraph group_group_tasks["Tasks"]
  node_node_task["Task API<br/>interface<br/>[task.py]"]
  node_node_regression["Regression<br/>task family<br/>[regression.py]"]
  node_node_control["Control<br/>task family<br/>[control.py]"]
end

subgraph group_group_optional["Optional branches"]
  node_node_gp["Genetic search<br/>optional optimizer<br/>[gp_controller.py]"]
  node_node_lm["LM prior<br/>optional prior"]
end

subgraph group_group_assets["Packaged assets"]
  node_node_reg_assets[("Regression data<br/>dataset assets<br/>[Nguyen-1.csv]")]
  node_node_ctrl_assets[("Control models<br/>artifact assets<br/>[model-td3.pkl]")]
  node_node_lm_assets[("LM checkpoint<br/>model asset<br/>[dynrnn.meta]")]
end

node_node_run -->|"loads"| node_node_config
node_node_core -->|"invokes"| node_node_train
node_node_run -->|"starts"| node_node_train
node_node_train -->|"uses"| node_node_task
node_node_train -->|"updates"| node_node_policy
node_node_policy -->|"implemented by"| node_node_rnn
node_node_train -->|"selects"| node_node_pg
node_node_train -->|"selects"| node_node_ppo
node_node_train -->|"selects"| node_node_pqt
node_node_rnn -->|"samples"| node_node_program
node_node_program -->|"constrains"| node_node_library
node_node_program -->|"evaluated by"| node_node_execute
node_node_execute -->|"uses"| node_node_functions
node_node_functions -.->|"accelerated by"| node_node_cyfunc
node_node_prior -->|"biases"| node_node_library
node_node_const -->|"extends"| node_node_library
node_node_task -->|"specializes to"| node_node_regression
node_node_task -->|"specializes to"| node_node_control
node_node_regression -->|"reads"| node_node_reg_assets
node_node_control -->|"reads"| node_node_ctrl_assets
node_node_train -->|"persists"| node_node_checkpoint
node_node_train -.->|"optional branch"| node_node_gp
node_node_train -.->|"optional branch"| node_node_lm
node_node_lm -->|"loads"| node_node_lm_assets
node_node_config -->|"configures"| node_node_prior
node_node_config -->|"configures"| node_node_task
node_node_config -->|"configures"| node_node_policy
node_node_config -.->|"enables"| node_node_gp
node_node_config -.->|"enables"| node_node_lm

click node_node_run "https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/run.py"
click node_node_core "https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/core.py"
click node_node_train "https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/train.py"
click node_node_program "https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/program.py"
click node_node_library "https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/library.py"
click node_node_execute "https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/execute.py"
click node_node_functions "https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/functions.py"
click node_node_cyfunc "https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/cyfunc.pyx"
click node_node_prior "https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/prior.py"
click node_node_const "https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/const.py"
click node_node_policy "https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/policy/policy.py"
click node_node_rnn "https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/policy/rnn_policy.py"
click node_node_pg "https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/policy_optimizer/pg_policy_optimizer.py"
click node_node_ppo "https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/policy_optimizer/ppo_policy_optimizer.py"
click node_node_pqt "https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/policy_optimizer/pqt_policy_optimizer.py"
click node_node_task "https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/task/task.py"
click node_node_regression "https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/task/regression/regression.py"
click node_node_control "https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/task/control/control.py"
click node_node_gp "https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/gp/gp_controller.py"
click node_node_lm "https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/language_model/language_model_prior.py"
click node_node_config "https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/config/config_common.json"
click node_node_checkpoint "https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/checkpoint.py"
click node_node_reg_assets "https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/task/regression/data/Nguyen-1.csv"
click node_node_ctrl_assets "https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/task/control/data/Pendulum-v0/model-td3.pkl"
click node_node_lm_assets "https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/language_model/model/saved_model/dynrnn.meta"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_run,node_node_core,node_node_train,node_node_program,node_node_library,node_node_execute,node_node_functions,node_node_cyfunc,node_node_prior,node_node_const,node_node_config,node_node_checkpoint toneBlue
class node_node_policy,node_node_rnn,node_node_pg,node_node_ppo,node_node_pqt toneAmber
class node_node_task,node_node_regression,node_node_control toneMint
class node_node_gp,node_node_lm toneRose
class node_node_reg_assets,node_node_ctrl_assets,node_node_lm_assets toneIndigo
```

## Components

### Core engine

Top-level orchestration, symbolic representation, and execution.

- [CLI run](https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/run.py): entrypoint · Command-line launcher for experiments. · `dso/dso/run.py`
- [Optimizer API](https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/core.py): orchestrator · Main DeepSymbolicOptimizer API used programmatically. · `dso/dso/core.py`
- [Training loop](https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/train.py): loop · Coordinates sampling, evaluation, updates, and logging. · `dso/dso/train.py`
- [Program](https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/program.py): symbolic IR · Candidate symbolic expression or policy representation. · `dso/dso/program.py`
- [Library](https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/library.py): token space · Defines available symbols and operators. · `dso/dso/library.py`
- [Execute](https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/execute.py): evaluator · Runs programs on task inputs to produce outputs or rewards. · `dso/dso/execute.py`
- [Functions](https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/functions.py): ops · Primitive math and functional building blocks. · `dso/dso/functions.py`
- [Native funcs](https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/cyfunc.pyx): accelerator · Cython fast path for function execution. · `dso/dso/cyfunc.pyx`
- [Priors](https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/prior.py): search bias · Handcrafted priors and constraints over programs. · `dso/dso/prior.py`
- [Constants](https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/const.py): token support · Floating constants and related token handling. · `dso/dso/const.py`
- [Configs](https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/config/config_common.json): configuration · JSON configuration layer for common, regression, control, and GP runs. · `dso/dso/config/config_common.json`
- [State & logs](https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/checkpoint.py): persistence · Checkpoints, TensorFlow state, metrics, and evaluation logging. · `dso/dso/checkpoint.py`

### Policy search

Learned sampler and interchangeable training objectives.

- [Policy model](https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/policy/policy.py): sequence model · Shared interface for the learned program sampler. · `dso/dso/policy/policy.py`
- [RNN policy](https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/policy/rnn_policy.py): autoregressive policy · RNN-based sampler that emits token sequences. · `dso/dso/policy/rnn_policy.py`
- [PG optimizer](https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/policy_optimizer/pg_policy_optimizer.py): update rule · Risk-seeking policy-gradient training. · `dso/dso/policy_optimizer/pg_policy_optimizer.py`
- [PPO optimizer](https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/policy_optimizer/ppo_policy_optimizer.py): update rule · PPO-based policy optimization. · `dso/dso/policy_optimizer/ppo_policy_optimizer.py`
- [PQT optimizer](https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/policy_optimizer/pqt_policy_optimizer.py): update rule · Priority-queue training over sampled programs. · `dso/dso/policy_optimizer/pqt_policy_optimizer.py`

### Tasks

Regression and control task families.

- [Task API](https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/task/task.py): interface · Common task contract for evaluation and extensions. · `dso/dso/task/task.py`
- [Regression](https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/task/regression/regression.py): task family · Symbolic regression on datasets and benchmarks. · `dso/dso/task/regression/regression.py`
- [Control](https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/task/control/control.py): task family · Symbolic control policies for RL environments. · `dso/dso/task/control/control.py`

### Optional branches

Alternative priors and inner-loop search components.

- [Genetic search](https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/gp/gp_controller.py): optional optimizer · Optional GP controller used for population seeding or hybrid search. · `dso/dso/gp/gp_controller.py`
- [LM prior](https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/language_model/language_model_prior.py): optional prior · Learned token prior from an offline language model. · `dso/dso/language_model/language_model_prior.py`

### Packaged assets

Bundled models, datasets, and experiment artifacts.

- [Regression data](https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/task/regression/data/Nguyen-1.csv): dataset assets · Bundled regression datasets and benchmark definitions. · `dso/dso/task/regression/data/Nguyen-1.csv`
- [Control models](https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/task/control/data/Pendulum-v0/model-td3.pkl): artifact assets · Pretrained anchor policies and environment-specific assets. · `dso/dso/task/control/data/Pendulum-v0/model-td3.pkl`
- [LM checkpoint](https://github.com/dso-org/deep-symbolic-optimization/blob/master/dso/dso/language_model/model/saved_model/dynrnn.meta): model asset · Saved language-model checkpoint used by the learned prior. · `dso/dso/language_model/model/saved_model/dynrnn.meta`

## Connections

- CLI run → Configs: loads · CLI experiments are driven by JSON configuration.
- Optimizer API → Training loop: invokes · Python API enters the shared training path.
- CLI run → Training loop: starts · Command-line entrypoint launches training.
- Training loop → Task API: uses · Training depends on the task interface for evaluation.
- Training loop → Policy model: updates · Training coordinates policy optimization.
- Policy model → RNN policy: implemented by · Primary learned sampler is RNN-based.
- Training loop → PG optimizer: selects · Config may choose a policy-gradient optimizer.
- Training loop → PPO optimizer: selects · Config may choose PPO.
- Training loop → PQT optimizer: selects · Config may choose priority-queue training.
- RNN policy → Program: samples · Policy emits token sequences that become programs.
- Program → Library: constrains · Program structure is defined over library tokens.
- Program → Execute: evaluated by · Candidate programs are executed on task inputs.
- Execute → Functions: uses · Execution relies on primitive functions.
- Functions → Native funcs: accelerated by · Native Cython path speeds up evaluation.
- Priors → Library: biases · Priors shape the search over available tokens.
- Constants → Library: extends · Constants add special token support.
- Task API → Regression: specializes to · Regression implements the shared task contract.
- Task API → Control: specializes to · Control implements the shared task contract.
- Regression → Regression data: reads · Regression experiments use bundled datasets.
- Control → Control models: reads · Control experiments use bundled environment models.
- Training loop → State & logs: persists · Training writes checkpoints and metrics.
- Training loop → Genetic search: optional branch · Hybrid GP search can feed candidate populations.
- Training loop → LM prior: optional branch · Learned language-model prior can bias sampling.
- LM prior → LM checkpoint: loads · The LM prior depends on saved checkpoint artifacts.
- Configs → Priors: configures · Config chooses priors and constraints.
- Configs → Task API: configures · Config selects task family and task-specific settings.
- Configs → Policy model: configures · Config selects sampler and model parameters.
- Configs → Genetic search: enables · GP can be turned on from configuration.
- Configs → LM prior: enables · Language-model prior can be turned on from configuration.
