synth

Documentation

Overview

Experimental — this package is not yet wired into the main framework.

Package synth provides synthetic data generation using generative models.

The primary entry point is MarketVAE, a Variational Autoencoder (VAE) that learns the distribution of input data and generates realistic synthetic samples. The model consists of:

• An encoder that maps input data to a latent distribution parameterized by mean and log-variance vectors.
• A decoder that reconstructs data from latent samples using the reparameterization trick (z = mu + sigma * epsilon).
• A loss function combining reconstruction error (MSE) with KL divergence to regularize the latent space.

Typical usage:

vae := synth.NewMarketVAE(synth.VAEConfig{
    InputDim:     10,
    LatentDim:    3,
    HiddenDims:   []int{32, 16},
    LearningRate: 0.001,
    NEpochs:      100,
})
err := vae.Train(data)
synthetic := vae.Generate(1000)
latent := vae.Encode(data)

(Stability: alpha)

Index

• type CrashConfig
• type CrashGenerator
  • func NewCrashGenerator(vae *MarketVAE, config CrashConfig) *CrashGenerator
  • func (cg *CrashGenerator) Generate(n int) [][]float64
  • func (cg *CrashGenerator) GenerateWithSeverity(n int, severity float64) [][]float64
• type MarketVAE
  • func NewMarketVAE(config VAEConfig) *MarketVAE
  • func (v *MarketVAE) Encode(data [][]float64) [][]float64
  • func (v *MarketVAE) Generate(n int) [][]float64
  • func (v *MarketVAE) Train(data [][]float64) error
• type VAEConfig

Types

type CrashConfig

type CrashConfig struct {
	// Severity controls the magnitude of extreme scenarios on a 1.0-10.0 scale.
	// Higher values produce more extreme tail events.
	Severity float64

	// Duration is the number of timesteps per generated crash scenario.
	Duration int

	// CorrelationSpike controls how much inter-asset correlations increase
	// during the crash. A value of 0 means no additional correlation; higher
	// values push all assets toward moving together.
	CorrelationSpike float64

	// Seed controls random number generation for reproducibility.
	// A value of 0 uses a non-deterministic seed.
	Seed int64
}

CrashConfig controls the behavior of CrashGenerator.

type CrashGenerator

type CrashGenerator struct {
	// contains filtered or unexported fields
}

CrashGenerator extends MarketVAE to generate extreme tail scenarios for stress testing. It biases latent-space sampling toward the tails of the distribution and injects correlated shocks to simulate market crash dynamics.

func NewCrashGenerator

func NewCrashGenerator(vae *MarketVAE, config CrashConfig) *CrashGenerator

NewCrashGenerator creates a CrashGenerator that uses the given VAE to produce extreme scenario samples. The severity in config is clamped to the [1.0, 10.0] range.

func (*CrashGenerator) Generate

func (cg *CrashGenerator) Generate(n int) [][]float64

Generate produces n extreme scenario samples using the configured severity. Each sample is a flattened sequence of length Duration * InputDim.

func (*CrashGenerator) GenerateWithSeverity

func (cg *CrashGenerator) GenerateWithSeverity(n int, severity float64) [][]float64

GenerateWithSeverity produces n extreme scenario samples at the given severity level (clamped to [1.0, 10.0]). Each sample is a sequence of Duration timesteps, returned as a flat slice of length Duration * InputDim.

The generator works by:

1. Sampling from the tails of the latent distribution (scaled by severity).
2. Injecting a correlated shock component so assets move together.
3. Applying temporal decay so the crash impact fades over the duration.

type MarketVAE

type MarketVAE struct {
	// contains filtered or unexported fields
}

MarketVAE is a Variational Autoencoder for synthetic data generation. It learns a smooth latent representation of the input data distribution and can generate new samples by decoding points from the latent space.

func NewMarketVAE

func NewMarketVAE(config VAEConfig) *MarketVAE

NewMarketVAE creates a new VAE with the given configuration. Weights are initialized using Xavier/Glorot uniform initialization.

func (*MarketVAE) Encode

func (v *MarketVAE) Encode(data [][]float64) [][]float64

Encode maps input data to latent representations by returning the mean vector of the encoder's posterior distribution for each sample.

func (*MarketVAE) Generate

func (v *MarketVAE) Generate(n int) [][]float64

Generate produces n synthetic samples by sampling from the latent space and decoding. The latent samples are drawn from the standard normal prior N(0,I).

func (*MarketVAE) Train

func (v *MarketVAE) Train(data [][]float64) error

Train trains the VAE on the provided data using mini-batch gradient descent. data is shaped [n_samples][input_dim].

type VAEConfig

type VAEConfig struct {
	// InputDim is the dimensionality of the input data.
	InputDim int

	// LatentDim is the dimensionality of the latent space.
	LatentDim int

	// HiddenDims specifies the sizes of hidden layers in the encoder and decoder.
	// The decoder uses these dimensions in reverse order.
	HiddenDims []int

	// LearningRate is the step size for gradient descent. Default: 0.001.
	LearningRate float64

	// NEpochs is the number of training epochs. Default: 100.
	NEpochs int

	// Seed controls random number generation for reproducibility.
	// A value of 0 uses a non-deterministic seed.
	Seed int64
}

VAEConfig controls the architecture and training of a MarketVAE.