api

import "github.com/umbralcalc/stochadex/pkg/api"

Package api provides configuration management and program generation for stochadex simulations. It handles YAML-based configuration loading, code generation, and execution orchestration for complex simulation setups including embedded runs and templated configurations.

Key Features:

• YAML configuration loading and validation
• Code generation from string templates
• Embedded simulation run support
• Socket-based communication configuration
• Runtime program execution

Usage Patterns:

• Load simulation configurations from YAML files
• Generate executable programs from templates
• Run simulations with embedded sub-simulations
• Configure socket-based data exchange

Index

• Variables
• func Run(config *ApiRunConfig, socket *SocketConfig)
• func RunWithParsedArgs(args ParsedArgs)
• func StepAndServeWebsocket(generator *simulator.ConfigGenerator, stepDelay time.Duration, handle string, address string)
• func WriteMainProgram(args ParsedArgs) string
• type ApiRunConfig
  • func LoadApiRunConfigFromYaml(path string) *ApiRunConfig
  • func (a *ApiRunConfig) GetConfigGenerator() *simulator.ConfigGenerator
• type ApiRunConfigStrings
  • func LoadApiRunConfigStringsFromYaml(path string) *ApiRunConfigStrings
• type EmbeddedRunConfig
• type EmbeddedRunConfigStrings
• type ParsedArgs
  • func ArgParse() ParsedArgs
• type PartitionConfigStrings
• type RunConfig
  • func (r *RunConfig) GetConfigGenerator() *simulator.ConfigGenerator
• type RunConfigStrings
• type SocketConfig
  • func LoadSocketConfigFromYaml(path string) *SocketConfig
  • func (s *SocketConfig) Active() bool

Variables

ApiCodeTemplate is the Go source template used to generate a runnable temporary main program that executes the requested run configuration.

var ApiCodeTemplate = `package main

import (
    "github.com/umbralcalc/stochadex/pkg/api"
    "github.com/umbralcalc/stochadex/pkg/simulator"
    {{.ExtraPackages}}
)

func main() {
    config := api.LoadApiRunConfigFromYaml("{{.ConfigFile}}")
    socket := api.LoadSocketConfigFromYaml("{{.SocketFile}}")
    {{.ExtraVars}}
    {{.ExtraCode}}
    api.Run(config, socket)
}`

func Run

func Run(config *ApiRunConfig, socket *SocketConfig)

Run executes the configured simulation. If a websocket socket is active, it serves real-time updates; otherwise, it runs to completion offline.

func RunWithParsedArgs

func RunWithParsedArgs(args ParsedArgs)

RunWithParsedArgs generates a temporary main program from the templated config and executes it via `go run`, enabling dynamic iteration wiring.

func StepAndServeWebsocket

func StepAndServeWebsocket(generator *simulator.ConfigGenerator, stepDelay time.Duration, handle string, address string)

StepAndServeWebsocket steps a simulation and streams state updates over a websocket using simulator.WebsocketOutputFunction.

Usage hints:

• The HTTP server mounts the websocket at handle and listens on address.
• stepDelay controls the delay between steps in milliseconds.

func WriteMainProgram

func WriteMainProgram(args ParsedArgs) string

WriteMainProgram renders ApiCodeTemplate to a /tmp/*main.go and returns the file path.

Usage hints:

• The generated program imports extra packages, declares extra variables, and wires iterations per the templated config.

type ApiRunConfig

ApiRunConfig is the concrete, YAML-loadable configuration for an API run: a main RunConfig and optional embedded runs.

type ApiRunConfig struct {
    Main     RunConfig           `yaml:"main"`
    Embedded []EmbeddedRunConfig `yaml:"embedded,omitempty"`
}

func LoadApiRunConfigFromYaml

func LoadApiRunConfigFromYaml(path string) *ApiRunConfig

LoadApiRunConfigFromYaml loads simulation configuration from YAML file.

This function reads a complete API run configuration from a YAML file, including main simulation configuration and optional embedded runs. It automatically initializes partition defaults and validates the configuration.

Parameters:

• path: Path to the YAML configuration file (must exist and be readable)

Returns:

• *ApiRunConfig: Loaded and initialized configuration ready for execution

YAML File Format: The YAML file must contain:

main:
  partitions:
    - name: "process1"
      iteration: "&continuous.WienerProcessIteration{}"
      params:
        variances: [0.1, 0.2]
      init_state_values: [0.0, 0.0]
      state_history_depth: 10
      state_width: 2
      seed: 42
  simulation:
    output_condition: "&simulator.StepCountOutputCondition{MaxSteps: 100}"
    output_function: "&simulator.StateTimeStorageOutputFunction{Store: store}"
    termination_condition: "&simulator.StepCountTerminationCondition{MaxSteps: 1000}"
    timestep_function: "&simulator.ConstantTimestepFunction{Timestep: 0.01}"
    init_time_value: 0.0
embedded:
  - name: "sub_simulation"
    partitions: [...]
    simulation: [...]

Error Handling:

• Panics on file read errors (file not found, permission denied)
• Panics on YAML parsing errors (malformed YAML, type mismatches)
• Automatically initializes partition defaults on success

Example:

config := LoadApiRunConfigFromYaml("simulation_config.yaml")
generator := config.GetConfigGenerator()
// Use generator to run the simulation

Performance Notes:

• Loads entire file into memory
• O(n) time complexity where n is the YAML file size
• Memory usage scales with configuration complexity

func (*ApiRunConfig) GetConfigGenerator

func (a *ApiRunConfig) GetConfigGenerator() *simulator.ConfigGenerator

GetConfigGenerator returns a ConfigGenerator for the main run. Any partition whose name matches an embedded run is replaced by an embedded simulation iteration wired to that embedded run.

type ApiRunConfigStrings

ApiRunConfigStrings is the string-templated configuration used to generate code for an API run (imports, variables, iteration factories).

type ApiRunConfigStrings struct {
    Main     RunConfigStrings           `yaml:"main"`
    Embedded []EmbeddedRunConfigStrings `yaml:"embedded,omitempty"`
}

func LoadApiRunConfigStringsFromYaml

func LoadApiRunConfigStringsFromYaml(path string) *ApiRunConfigStrings

LoadApiRunConfigStringsFromYaml loads the templated config from YAML and validates it for code generation.

type EmbeddedRunConfig

EmbeddedRunConfig names and embeds an additional RunConfig that can be wired into a partition in the main run.

type EmbeddedRunConfig struct {
    Name string    `yaml:"name"`
    Run  RunConfig `yaml:",inline"`
}

type EmbeddedRunConfigStrings

EmbeddedRunConfigStrings names and provides string-templated inputs for an embedded simulation run.

type EmbeddedRunConfigStrings struct {
    Name string           `yaml:"name"`
    Run  RunConfigStrings `yaml:",inline"`
}

type ParsedArgs

ParsedArgs bundles CLI-derived inputs for running the API. Includes the YAML config path, optional socket config path, and the string-templated configuration used to generate a runnable main.

type ParsedArgs struct {
    ConfigStrings *ApiRunConfigStrings
    ConfigFile    string
    SocketFile    string
}

func ArgParse

func ArgParse() ParsedArgs

ArgParse parses CLI flags into a ParsedArgs, loading ApiRunConfigStrings from the provided YAML path for template hydration.

type PartitionConfigStrings

PartitionConfigStrings describes a partition in its string-templated form for code generation and dynamic program construction.

This struct is used to generate Go code from YAML configurations, allowing for flexible simulation setups without hardcoded partition types. It supports dynamic iteration creation, package imports, and variable injection.

Fields:

• Name: Partition name (must be unique within a simulation)
• Iteration: Go expression that constructs the iteration (e.g., “&continuous.WienerProcessIteration{}”)
• ExtraPackages: Import paths required by the Iteration expression or ExtraVars
• ExtraVars: Ad-hoc variable declarations injected into the generated main function

Code Generation: The Iteration field is evaluated as Go code, allowing for parameterized iteration construction. ExtraVars provide additional context for the generated code.

Example:

config := PartitionConfigStrings{
    Name: "brownian_motion",
    Iteration: "&continuous.WienerProcessIteration{}",
    ExtraPackages: []string{"github.com/umbralcalc/stochadex/pkg/continuous"},
    ExtraVars: []map[string]string{
        {"variance": "0.1"},
        {"dimensions": "2"},
    },
}

Validation:

• Iteration must be a valid Go expression
• ExtraPackages must be valid import paths
• ExtraVars must be valid Go variable declarations

type PartitionConfigStrings struct {
    Name          string              `yaml:"name"`
    Iteration     string              `yaml:"iteration,omitempty"`
    ExtraPackages []string            `yaml:"extra_packages,omitempty"`
    ExtraVars     []map[string]string `yaml:"extra_vars,omitempty"`
}

type RunConfig

RunConfig represents a complete simulation run configuration with partitions and simulation settings.

This struct combines partition configurations with simulation control parameters to define a complete simulation run. It serves as the primary configuration structure for YAML-based simulation setup.

Fields:

• Partitions: List of partition configurations defining the simulation state
• Simulation: Simulation control parameters (not loaded from YAML directly)

YAML Structure:

partitions:
  - name: "process1"
    iteration: "&continuous.WienerProcessIteration{}"
    params:
      variances: [0.1, 0.2]
    init_state_values: [0.0, 0.0]
  - name: "process2"
    iteration: "&discrete.PoissonProcessIteration{}"
    params:
      rates: [0.5, 1.0]
    init_state_values: [0.0, 0.0]

Related Types:

• See simulator.PartitionConfig for partition configuration details
• See simulator.SimulationConfig for simulation control parameters
• See ApiRunConfig for API-level configuration with embedded runs

type RunConfig struct {
    Partitions []simulator.PartitionConfig `yaml:"partitions"`
    Simulation simulator.SimulationConfig  `yaml:"-"`
}

func (*RunConfig) GetConfigGenerator

func (r *RunConfig) GetConfigGenerator() *simulator.ConfigGenerator

GetConfigGenerator constructs a ConfigGenerator preloaded with the run’s SimulationConfig and Partitions.

type RunConfigStrings

RunConfigStrings provides the string-templated inputs required to generate a runnable main for a simulation run.

type RunConfigStrings struct {
    Partitions []PartitionConfigStrings          `yaml:"partitions"`
    Simulation simulator.SimulationConfigStrings `yaml:"simulation"`
}

type SocketConfig

SocketConfig configures an optional real-time websocket used to stream simulation updates.

type SocketConfig struct {
    Address          string `yaml:"address"`
    Handle           string `yaml:"handle"`
    MillisecondDelay uint64 `yaml:"millisecond_delay"`
}

func LoadSocketConfigFromYaml

func LoadSocketConfigFromYaml(path string) *SocketConfig

LoadSocketConfigFromYaml loads a SocketConfig from YAML. If the path is empty, it returns a zero-valued config and logs that sockets are disabled.

func (*SocketConfig) Active

func (s *SocketConfig) Active() bool

Active reports whether the websocket server should be started.

Generated by gomarkdoc