Public Experiments
The public experiment runner executes the packaged validation configurations
used by the benchmark cards and release checks. Each JSON config selects a
dataset or synthetic problem, model family, solver settings, optimization
budget, and output path for reproducible local validation.
Use the console command when installed, or call the module directly:
silva-experiment --list-configs
silva-experiment --show-config solver_sweep
silva-experiment --config solver_sweep --output-dir outputs
python -m silva_networks.public_experiments --config graph_silva_smoke
Nested values can be changed without editing the packaged file:
silva-experiment \
--config solver_sweep \
--set scale=0.15 \
--set solvers.0.max_iter=60 \
--set solvers.0.tol=1e-7 \
--output-dir outputs
Override values are parsed as JSON when possible, so numbers, booleans, arrays,
and objects retain their types.
Configuration Contract
Every configuration contains name and kind. Model runs then add the
relevant state dimensions, branch choices, solver block, dataset fields, and
optimization budget. For example:
{
"name": "solver_sweep",
"kind": "solver_sweep",
"seed": 11,
"dim": 6,
"scale": 0.2,
"solvers": [
{"solver": "picard", "max_iter": 40, "tol": 1e-5, "alpha": 0.7}
]
}
For the solver family, the generated records contain iterations,
converged, residual, spectral_radius, and jacobian_norm_estimate. Model
families add loss, accuracy or regression metrics, tensor shapes, and the
configuration choices needed to interpret them.
SILVA Interpretation
The runner does not define a second model API. It constructs the same public
SILVA layers and solves
\[
z^\star=f_\theta(z^\star,x)
\]
with a serialized SolverConfig. This keeps a JSON experiment tied directly
to the Python objects documented elsewhere in the API.
The runner writes JSON metrics and keeps benchmark claims separate from package
API behavior. For the curated results, see Benchmark Cards
and Results.
SignedLocal
Bases: Module
Small custom local branch used by the public custom-operator experiment.
Source code in src/silva_networks/public_experiments.py
| class SignedLocal(torch.nn.Module):
"""Small custom local branch used by the public custom-operator experiment."""
def __init__(self, dim: int):
super().__init__()
self.proj = torch.nn.Linear(dim, dim, bias=False)
def forward(self, z: torch.Tensor, edge_index: torch.Tensor | None = None) -> torch.Tensor:
messages = torch.tanh(self.proj(z))
if edge_index is None:
return messages
src, dst = edge_index
out = torch.zeros_like(messages)
out.index_add_(0, dst, messages[src])
return out
|
apply_overrides
apply_overrides(config, overrides)
Apply dotted CLI overrides to a JSON config in place.
Source code in src/silva_networks/public_experiments.py
| def apply_overrides(config: dict[str, Any], overrides: list[str]) -> None:
"""Apply dotted CLI overrides to a JSON config in place."""
for override in overrides:
if "=" not in override:
raise ValueError(f"Override must have KEY=VALUE form: {override!r}")
key, raw_value = override.split("=", 1)
set_config_value(config, key.split("."), parse_override_value(raw_value))
|
list_configs
Return built-in public config names, paths, and experiment kinds.
Source code in src/silva_networks/public_experiments.py
| def list_configs() -> list[dict[str, str]]:
"""Return built-in public config names, paths, and experiment kinds."""
rows = []
for path in sorted(CONFIG_DIR.glob("*.json")):
config = json.loads(path.read_text())
rows.append(
{
"name": config.get("name", path.stem),
"kind": config.get("kind", "unknown"),
"path": f"silva_networks/{path.relative_to(ROOT)}",
}
)
return rows
|
load_config
Load a config by filesystem path or built-in config name.
Source code in src/silva_networks/public_experiments.py
| def load_config(value: str | Path) -> dict[str, Any]:
"""Load a config by filesystem path or built-in config name."""
path = resolve_config_path(value)
return json.loads(path.read_text())
|
make_global_kwargs
make_global_kwargs(config, default_global)
Return global-operator kwargs from JSON, including top-k defaults.
Source code in src/silva_networks/public_experiments.py
| def make_global_kwargs(
config: dict[str, Any],
default_global: str,
) -> dict[str, Any] | list[dict[str, Any] | None] | None:
"""Return global-operator kwargs from JSON, including top-k defaults."""
if "global_kwargs" in config:
return config["global_kwargs"]
global_term = config.get("global_term", default_global)
if "global_k" in config:
k = int(config["global_k"])
elif "k_neighbors" in config:
k = int(config["k_neighbors"])
else:
return None
if isinstance(global_term, str):
return {"k": k} if global_term in {"topk", "topk_attention"} else None
if isinstance(global_term, list):
return [
{"k": k} if item in {"topk", "topk_attention"} else None
for item in global_term
]
return None
|
make_local_kwargs
make_local_kwargs(config, default_local)
Return local-operator kwargs from JSON, including top-k defaults.
Source code in src/silva_networks/public_experiments.py
| def make_local_kwargs(config: dict[str, Any], default_local: str) -> dict[str, Any] | list[dict[str, Any] | None] | None:
"""Return local-operator kwargs from JSON, including top-k defaults."""
if "local_kwargs" in config:
return config["local_kwargs"]
local = config.get("local", default_local)
if "k" not in config:
return None
k = int(config["k"])
if isinstance(local, str):
return {"k": k} if local in {"topk", "channel_knn", "vision_knn"} else None
if isinstance(local, list):
return [
{"k": k} if item in {"topk", "channel_knn", "vision_knn"} else None
for item in local
]
return None
|
parse_override_value
parse_override_value(raw_value)
Parse a CLI override value as JSON, falling back to a string.
Source code in src/silva_networks/public_experiments.py
| def parse_override_value(raw_value: str) -> Any:
"""Parse a CLI override value as JSON, falling back to a string."""
try:
return json.loads(raw_value)
except json.JSONDecodeError:
return raw_value
|
resolve_config_path
resolve_config_path(value)
Resolve a path, built-in config stem, or built-in config filename.
Source code in src/silva_networks/public_experiments.py
| def resolve_config_path(value: str | Path) -> Path:
"""Resolve a path, built-in config stem, or built-in config filename."""
raw = Path(value).expanduser()
if raw.exists():
return raw
candidates = [CONFIG_DIR / raw.name]
if raw.suffix != ".json":
candidates.append(CONFIG_DIR / f"{raw.name}.json")
for candidate in candidates:
if candidate.exists():
return candidate
available = ", ".join(path.stem for path in sorted(CONFIG_DIR.glob("*.json")))
raise FileNotFoundError(f"Could not find config {value!r}. Available configs: {available}")
|
set_config_value
set_config_value(container, path, value)
Set a nested config field. Numeric path parts address list indices.
Source code in src/silva_networks/public_experiments.py
| def set_config_value(container: dict[str, Any] | list[Any], path: list[str], value: Any) -> None:
"""Set a nested config field. Numeric path parts address list indices."""
if not path or any(part == "" for part in path):
raise ValueError("Override keys must be non-empty")
target: dict[str, Any] | list[Any] = container
for part in path[:-1]:
if isinstance(target, list):
target = target[int(part)]
continue
if part not in target or target[part] is None:
target[part] = {}
target = target[part]
if not isinstance(target, (dict, list)):
raise TypeError(f"Cannot descend into non-container override path: {'.'.join(path)}")
final = path[-1]
if isinstance(target, list):
target[int(final)] = value
else:
target[final] = value
|
Where to Go Next