axon/learn.goal

// Copyright (c) 2019, The Emergent Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

package axon

import (
	"cogentcore.org/core/math32"
	"cogentcore.org/core/math32/minmax"
	"cogentcore.org/lab/base/randx"
	"cogentcore.org/lab/gosl/slbool"
	"github.com/emer/axon/v2/chans"
	"github.com/emer/axon/v2/kinase"
)

////////  learn.go contains the learning params and functions for axon

//gosl:start
//gosl:import "github.com/emer/axon/v2/kinase"

// LearnCaParams parameterizes the neuron-level calcium signals driving learning:
// LearnCa = NMDA + VGCC Ca sources, where VGCC can be simulated from spiking or
// use the more complex and dynamaic VGCC channel directly.
// LearnCa is then integrated in a cascading manner at multiple time scales:
// CaM (as in calmodulin), CaP (ltP, CaMKII, plus phase), CaD (ltD, DAPK1, minus phase).
type LearnCaParams struct {

	// Norm is the denominator used for normalizing [LearnCa], so the
	// max is roughly 1 - 1.5 or so, which works best in terms of previous
	// standard learning rules, and overall learning performance.
	Norm float32 `default:"80"`

	// SpikeVGCC uses spikes to generate VGCC instead of actual VGCC current.
	// See SpikeVGCCa for calcium contribution from each spike.
	SpikeVGCC slbool.Bool `default:"true"`

	// SpikeVgccCa is the multiplier on spike for computing Ca contribution
	// to [LearnCa], in SpikeVGCC mode.
	SpikeVgccCa float32 `default:"35"`

	// VgccTau is the time constant of decay for VgccCa calcium.
	// It is highly transient around spikes, so decay and diffusion
	// factors are more important than for long-lasting NMDA factor.
	// VgccCa is integrated separately in [VgccCaInt] prior to adding
	// into NMDA Ca in [LearnCa].
	VgccTau float32 `default:"10"`

	// Dt are time constants for integrating [LearnCa] across
	// M, P and D cascading levels.
	Dt kinase.CaDtParams `display:"inline"`

	// VgccDt rate = 1 / tau
	VgccDt float32 `display:"-" json:"-" xml:"-" edit:"-"`

	// NormInv = 1 / Norm
	NormInv float32 `display:"-" json:"-" xml:"-" edit:"-"`

	pad, pad2 int32
}

func (lc *LearnCaParams) Defaults() {
	lc.Norm = 80
	lc.SpikeVGCC.SetBool(true)
	lc.SpikeVgccCa = 35
	lc.VgccTau = 10
	lc.Dt.Defaults()
	lc.Dt.MTau = 2
	lc.Update()
}

func (lc *LearnCaParams) Update() {
	lc.Dt.Update()
	lc.VgccDt = 1 / lc.VgccTau
	lc.NormInv = 1 / lc.Norm
}

func (lc *LearnCaParams) ShouldDisplay(field string) bool {
	switch field {
	case "SpikeVgccCa":
		return lc.SpikeVGCC.IsTrue()
	default:
		return true
	}
}

// VgccCa updates the simulated VGCC calcium from spiking, if that option is selected,
// and performs time-integration of VgccCa
func (lc *LearnCaParams) VgccCaFromSpike(ctx *Context, ni, di uint32) {
	if lc.SpikeVGCC.IsTrue() {
		Neurons[ni, di, VgccCa] = lc.SpikeVgccCa * Neurons[ni, di, Spike]
	}
	Neurons[ni, di, VgccCaInt] += Neurons[ni, di, VgccCa] - lc.VgccDt*Neurons[ni, di, VgccCaInt]
	// Dt only affects decay, not rise time
}

// LearnCas updates the LearnCa value and its cascaded values, based on NMDA, VGCC Ca
// it first calls VgccCa to update the spike-driven version of that variable, and
// perform its time-integration.
func (lc *LearnCaParams) LearnCas(ctx *Context, ni, di uint32) {
	lc.VgccCaFromSpike(ctx, ni, di)
	Neurons[ni, di, LearnCa] = lc.NormInv * (Neurons[ni, di, NmdaCa] + Neurons[ni, di, VgccCaInt])
	Neurons[ni, di, LearnCaM] += lc.Dt.MDt * (Neurons[ni, di, LearnCa] - Neurons[ni, di, LearnCaM])
	Neurons[ni, di, LearnCaP] += lc.Dt.PDt * (Neurons[ni, di, LearnCaM] - Neurons[ni, di, LearnCaP])
	Neurons[ni, di, LearnCaD] += lc.Dt.DDt * (Neurons[ni, di, LearnCaP] - Neurons[ni, di, LearnCaD])
	Neurons[ni, di, CaDiff] = Neurons[ni, di, LearnCaP] - Neurons[ni, di, LearnCaD]
}

////////  TrgAvgActParams

// TrgAvgActParams govern the target and actual long-term average activity in neurons.
// Target value is adapted by neuron-wise error and difference in actual vs. target.
// drives synaptic scaling at a slow timescale (Network.SlowInterval).
type TrgAvgActParams struct {

	// GiBaseInit sets an initial [GiBase] value, as a proportion of TrgRange.Max - [TrgAvg].
	// This gives neurons differences in intrinsic inhibition / leak as a starting bias.
	// This is independent of using the target values to scale synaptic weights. Only used if > 0.
	GiBaseInit float32 `default:"0"`

	// RescaleOn is whether to use target average activity mechanism to rescale
	// synaptic weights, so that activity tracks the target values.
	RescaleOn slbool.Bool `default:"true"`

	// ErrLRate is the learning rate for adjustments to [TrgAvg] value based on the
	// neuron-level error signal. Population TrgAvg values are renormalized to
	// a fixed overall average, in TrgRange. Generally, deviating from the default value
	// of this parameter doesn't make much difference.
	ErrLRate float32 `default:"0.02"`

	// SynScaleRate is a rate parameter for how much to scale synaptic weights
	// in proportion to the [AvgDif] between target and actual proportion activity.
	// This determines the effective strength of the constraint, and larger models
	// may need more than the weaker default value.
	SynScaleRate float32 `default:"0.005,0.0002"`

	// SubMean is the amount of the mean [TrgAvg] change to subtract when updating.
	// 1 = full zero sum changes. 1 works best in general, but in some cases it
	// may be better to start with 0 and then increase using network SetSubMean
	// method at a later point.
	SubMean float32 `default:"0,1"`

	// Permute the order of TrgAvg values within layer. Otherwise they are just
	// assigned in order from highest to lowest for easy visualization.
	// Generally must be true if any topographic weights are being used.
	Permute slbool.Bool `default:"true"`

	// Pool means use pool-level target values if pool-level inhibition and
	// 4D pooled layers are present. If pool sizes are relatively small,
	// then may not be useful to distribute targets just within pool.
	Pool slbool.Bool

	pad int32

	// TrgRange is the range of target normalized average activations.
	// Individual neuron [TrgAvg] values are assigned values within this range,
	// and clamped within this range. This is a critical parameter and the default
	// usually works best.
	TrgRange minmax.F32 `default:"{'Min':0.5,'Max':2}"`
}

func (ta *TrgAvgActParams) Update() {
}

func (ta *TrgAvgActParams) Defaults() {
	ta.RescaleOn.SetBool(true)
	ta.ErrLRate = 0.02
	ta.SynScaleRate = 0.005
	ta.SubMean = 1 // 1 in general beneficial
	ta.TrgRange.Set(0.5, 2)
	ta.Permute.SetBool(true)
	ta.Pool.SetBool(true)
	ta.Update()
}

func (ta *TrgAvgActParams) ShouldDisplay(field string) bool {
	switch field {
	case "RescaleOn", "GiBaseInit":
		return true
	case "TrgRange":
		return ta.RescaleOn.IsTrue() || ta.GiBaseInit > 0
	default:
		return ta.RescaleOn.IsTrue()
	}
}

////////  RLRateParams

// RLRateParams are recv neuron learning rate modulation parameters.
// Has two factors: the derivative of the sigmoid based on CaD
// activity levels, and based on the phase-wise differences in activity (Diff).
type RLRateParams struct {

	// On toggles use of learning rate modulation.
	On slbool.Bool `default:"true"`

	// SigmoidLinear uses a linear sigmoid function: if act > .5: 1-act; else act
	// otherwise use the actual sigmoid derivative which is squared: a(1-a).
	SigmoidLinear slbool.Bool `default:"true"`

	// SigmoidMin is the minimum learning rate multiplier for sigmoidal
	// act (1-act) factor, which prevents lrate from going too low for extreme values.
	// Set to 1 to disable Sigmoid derivative factor, which is default for Target layers.
	SigmoidMin float32 `default:"0.05,1"`

	// Diff modulates learning rate as a function of plus - minus differences.
	Diff slbool.Bool

	// SpikeThr is the threshold on Max(CaP, CaD) below which Min lrate applies.
	// Must be > 0 to prevent div by zero.
	SpikeThr float32 `default:"0.1"`

	// DiffThr is the threshold on recv neuron error delta, i.e., |CaP - CaD|
	//  below which lrate is at Min value.
	DiffThr float32 `default:"0.02"`

	// Min is the minimum learning rate value when |CaP - CaD| Diff is below DiffThr.
	Min float32 `default:"0.001"`

	pad int32
}

func (rl *RLRateParams) Update() {
}

func (rl *RLRateParams) Defaults() {
	rl.On.SetBool(true)
	rl.SigmoidLinear.SetBool(true)
	rl.SigmoidMin = 0.05
	rl.Diff.SetBool(true)
	rl.SpikeThr = 0.1
	rl.DiffThr = 0.02
	rl.Min = 0.001
	rl.Update()
}

func (rl *RLRateParams) ShouldDisplay(field string) bool {
	switch field {
	case "On":
		return true
	case "Diff", "SigmoidMin", "SigmoidLinear":
		return rl.On.IsTrue()
	default:
		return rl.On.IsTrue() && rl.Diff.IsTrue()
	}
}

// RLRateSigDeriv returns the sigmoid derivative learning rate
// factor as a function of spiking activity, with mid-range values having
// full learning and extreme values a reduced learning rate:
// deriv = 4*act*(1-act) or linear: if act > .5: 2*(1-act); else 2*act
// The activity should be CaP and the layer maximum is used
// to normalize that to a 0-1 range.
func (rl *RLRateParams) RLRateSigDeriv(act float32, laymax float32) float32 {
	if rl.On.IsFalse() || laymax == 0 {
		return 1.0
	}
	ca := min(act/laymax, 1.0)
	var lr float32
	if rl.SigmoidLinear.IsTrue() {
		if ca < 0.5 {
			lr = 2 * ca
		} else {
			lr = 2 * (1 - ca)
		}
	} else {
		lr = 4.0 * ca * (1 - ca) // .5 * .5 = .25 = peak
	}
	if lr < rl.SigmoidMin {
		lr = rl.SigmoidMin
	}
	return lr
}

// RLRateDiff returns the learning rate as a function of difference between
// CaP and CaD values
func (rl *RLRateParams) RLRateDiff(scap, scad float32) float32 {
	if rl.On.IsFalse() || rl.Diff.IsFalse() {
		return 1.0
	}
	smax := math32.Max(scap, scad)
	if smax > rl.SpikeThr { // avoid div by 0
		dif := math32.Abs(scap - scad)
		if dif < rl.DiffThr {
			return rl.Min
		}
		return (dif / smax)
	}
	return rl.Min
}

// LearnNeuronParams manages learning-related parameters at the neuron-level.
// This is mainly the running average activations that drive learning
type LearnNeuronParams struct {

	// CaLearn parameterizes the neuron-level calcium signals driving learning:
	// LearnCa = NMDA + VGCC Ca sources, where VGCC can be simulated from spiking
	// or use the more complex and dynamic VGCC channel directly.  LearnCa is then
	// integrated in a cascading manner at multiple time scales:
	// LearnCaM (as in calmodulin), LearnCaP (ltP, CaMKII, plus phase),
	// LearnCaD (ltD, DAPK1, minus phase).
	CaLearn LearnCaParams `display:"inline"`

	// CaSpike parameterizes the neuron-level spike-driven calcium signals:
	// CaM (calmodulin), CaP (ltP, CaMKII, plus phase), CaD (ltD, DAPK1, minus phase).
	// These values are used in various cases as a proxy for the activation (spiking)
	// based learning signal.
	CaSpike kinase.CaSpikeParams `display:"inline"`

	// NMDA channel parameters used for learning, vs. the ones driving activation.
	// This allows exploration of learning parameters independent of their effects
	// on active maintenance contributions of NMDA, and may be supported by different
	// receptor subtypes.
	LearnNMDA chans.NMDAParams `display:"inline"`

	// TrgAvgAct has the synaptic scaling parameters for regulating overall average
	// activity compared to neuron's own target level.
	TrgAvgAct TrgAvgActParams `display:"inline"`

	// RLRate has the recv neuron learning rate modulation params: an additional
	// error-based modulation of learning for receiver side:
	// RLRate = |CaP - CaD| / Max(CaP, CaD)
	RLRate RLRateParams `display:"inline"`

	// NeuroMod parameterizes neuromodulation effects on learning rate and activity,
	// as a function of layer-level DA and ACh values, which are updated from global
	// Context values, and computed from reinforcement learning algorithms.
	NeuroMod NeuroModParams `display:"inline"`
}

func (ln *LearnNeuronParams) Update() {
	ln.CaLearn.Update()
	ln.CaSpike.Update()
	ln.LearnNMDA.Update()
	ln.TrgAvgAct.Update()
	ln.RLRate.Update()
	ln.NeuroMod.Update()
}

func (ln *LearnNeuronParams) Defaults() {
	ln.CaLearn.Defaults()
	ln.CaSpike.Defaults()
	ln.LearnNMDA.Defaults()
	ln.LearnNMDA.ITau = 1
	ln.LearnNMDA.Update()
	ln.TrgAvgAct.Defaults()
	ln.RLRate.Defaults()
	ln.NeuroMod.Defaults()
}

// InitNeuronCa initializes the neuron-level calcium learning and spking variables.
// Called by InitWeights (at start of learning).
func (ln *LearnNeuronParams) InitNeuronCa(ctx *Context, ni, di uint32) {
	Neurons[ni, di, GnmdaLrn] = 0
	Neurons[ni, di, NmdaCa] = 0

	Neurons[ni, di, VgccCa] = 0
	Neurons[ni, di, VgccCaInt] = 0

	Neurons[ni, di, LearnCa] = 0

	Neurons[ni, di, CaM] = 0
	Neurons[ni, di, CaP] = 0
	Neurons[ni, di, CaD] = 0

	Neurons[ni, di, CaSyn] = 0
	Neurons[ni, di, LearnCaM] = 0
	Neurons[ni, di, LearnCaP] = 0
	Neurons[ni, di, LearnCaD] = 0
	Neurons[ni, di, CaDiff] = 0
}

// LearnNMDAFromRaw updates the separate NMDA conductance and calcium values
// based on GeTot = GeRaw + external ge conductance.  These are the variables
// that drive learning -- can be the same as activation but also can be different
// for testing learning Ca effects independent of activation effects.
func (ln *LearnNeuronParams) LearnNMDAFromRaw(ctx *Context, ni, di uint32, geTot float32) {
	geEff := max(geTot, 0.0)
	vmd := Neurons[ni, di, VmDend]
	Neurons[ni, di, GnmdaLrn] = ln.LearnNMDA.NMDASyn(Neurons[ni, di, GnmdaLrn], geEff)
	gnmda := ln.LearnNMDA.Gnmda(Neurons[ni, di, GnmdaLrn], vmd)
	Neurons[ni, di, NmdaCa] = float32(gnmda * ln.LearnNMDA.CaFromV(vmd))
}

// CaFromSpike updates all spike-driven calcium variables, including LearnCa and CaSpike.
// Computed after new activation for current cycle is updated.
func (ln *LearnNeuronParams) CaFromSpike(ctx *Context, ni, di uint32) {
	caM := Neurons[ni, di, CaM]
	caP := Neurons[ni, di, CaP]
	caD := Neurons[ni, di, CaD]
	spike := Neurons[ni, di, Spike]
	ln.CaSpike.CaMFromSpike(spike, &caM, &caP, &caD)
	Neurons[ni, di, CaM] = caM
	Neurons[ni, di, CaP] = caP
	Neurons[ni, di, CaD] = caD

	caSyn := Neurons[ni, di, CaSyn]
	caSyn = ln.CaSpike.CaSynFromSpike(spike, caSyn)
	Neurons[ni, di, CaSyn] = caSyn

	ln.CaLearn.LearnCas(ctx, ni, di)
}

////////  SWtParams

// SigFun is the sigmoid function for value w in 0-1 range, with gain and offset params
func SigFun(w, gain, off float32) float32 {
	if w <= 0 {
		return 0
	}
	if w >= 1 {
		return 1
	}
	return (1 / (1 + math32.Pow((off*(1-w))/w, gain)))
}

// SigFun61 is the sigmoid function for value w in 0-1 range, with default gain = 6, offset = 1 params
func SigFun61(w float32) float32 {
	if w <= 0 {
		return 0
	}
	if w >= 1 {
		return 1
	}
	pw := (1 - w) / w
	return (1 / (1 + pw*pw*pw*pw*pw*pw))
}

// SigInvFun is the inverse of the sigmoid function
func SigInvFun(w, gain, off float32) float32 {
	if w <= 0 {
		return 0
	}
	if w >= 1 {
		return 1
	}
	return 1.0 / (1.0 + math32.Pow((1.0-w)/w, 1/gain)/off)
}

// SigInvFun61 is the inverse of the sigmoid function, with default gain = 6, offset = 1 params
func SigInvFun61(w float32) float32 {
	if w <= 0 {
		return 0
	}
	if w >= 1 {
		return 1
	}
	rval := 1.0 / (1.0 + math32.Pow((1.0-w)/w, 1.0/6.0))
	return rval
}

// SWtInitParams for initial SWt (slow, structural weight) values.
type SWtInitParams struct {

	// SPct is how much of the initial random weights to capture in the
	// slow, structural SWt values, with the rest going into the online leanring
	// LWt values. 1 gives the strongest initial biasing effect, for larger
	// models that need more structural support. 0.5 should work for most models
	// where stronger constraints are not needed.
	SPct float32 `min:"0" max:"1" default:"0,1,0.5"`

	// Mean is the target mean weight value across receiving neuron's pathway.
	// The mean SWt values are constrained to remain at this value.
	// Some pathways may benefit from lower mean of .4.
	Mean float32 `default:"0.5,0.4"`

	// Var is the initial variance in weight values, prior to constraints.
	Var float32 `default:"0.25"`

	// Sym symmetrizes the initial weight values with those in reciprocal pathway.
	// Typically true for bidirectional excitatory connections.
	Sym slbool.Bool `default:"true"`
}

func (sp *SWtInitParams) Defaults() {
	sp.SPct = 0.5
	sp.Mean = 0.5
	sp.Var = 0.25
	sp.Sym.SetBool(true)
}

func (sp *SWtInitParams) Update() {
}

// SWtAdaptParams manages adaptation of the [SWt] (slow, structural weight) values.
type SWtAdaptParams struct {

	// On enables adaptation of [SWt] values at a slower time scale. If false, SWt
	// values are not updated, in which case it is generally good to set Init.SPct=0 too.
	On slbool.Bool

	// LRate is the learning rate multiplier on the accumulated [DWt] values
	// (which already have fast LRate applied), to drive updating of [SWt]
	// during slow outer loop updating. Lower values impose stronger constraints,
	// for larger networks that need more structural support, e.g., 0.001 is better
	// after 1,000 epochs in large models. 0.1 is fine for smaller models.
	LRate float32 `default:"0.1,0.01,0.001,0.0002"`

	// SubMean is the amount of the mean to subtract from [SWt] delta when updating,
	// to impose a zero-sum constraint on overall structural weight strengths.
	// Generally best to set to 1. There is a separate SubMean factor for [LWt].
	SubMean float32 `default:"1"`

	// SigGain is the gain of the sigmoidal constrast enhancement function
	// used to transform learned, linear [LWt] values into [Wt] values.
	// This is critical to offset the damping effect of exponential soft bounding,
	// but some special cases with different learning rules may benefit by making
	// this linear (1) instead.
	SigGain float32 `default:"6"`
}

func (sp *SWtAdaptParams) Defaults() {
	sp.On.SetBool(true)
	sp.LRate = 0.1
	sp.SubMean = 1
	sp.SigGain = 6
	sp.Update()
}

func (sp *SWtAdaptParams) Update() {
}

func (sp *SWtAdaptParams) ShouldDisplay(field string) bool {
	switch field {
	case "On":
		return true
	default:
		return sp.On.IsTrue()
	}
}

// SWtParams manages structural, slowly adapting weight values [SWt],
// in terms of initialization and updating over course of learning.
// SWts impose initial and slowly adapting constraints on neuron connectivity
// to encourage differentiation of neuron representations and overall good behavior
// in terms of not hogging the representational space.
// The [TrgAvg] activity constraint is not enforced through SWt: it needs to be
// more dynamic and is supported by the regular learned weights [LWt].
type SWtParams struct {

	// Init controls the initialization of [SWt] values.
	Init SWtInitParams `display:"inline"`

	// Adapt controls adaptation of [SWt] values in response to [LWt] learning.
	Adapt SWtAdaptParams `display:"inline"`

	// Limit limits the range of [SWt] values, so that they do not fully
	// determine the effective overall weight value.
	Limit minmax.F32 `default:"{'Min':0.2,'Max':0.8}" display:"inline"`
}

func (sp *SWtParams) Defaults() {
	sp.Init.Defaults()
	sp.Adapt.Defaults()
	sp.Limit.Set(0.2, 0.8)
}

func (sp *SWtParams) Update() {
	sp.Init.Update()
	sp.Adapt.Update()
}

// WtVal returns the effective Wt value given the SWt and LWt values
func (sp *SWtParams) WtValue(swt, lwt float32) float32 {
	return swt * sp.SigFromLinWt(lwt)
}

// ClipSWt returns SWt value clipped to valid range
func (sp *SWtParams) ClipSWt(swt float32) float32 {
	return sp.Limit.ClampValue(swt)
}

// ClipWt returns Wt value clipped to 0-1 range
func (sp *SWtParams) ClipWt(wt float32) float32 {
	if wt > 1 {
		return 1
	}
	if wt < 0 {
		return 0
	}
	return wt
}

// SigFromLinWt returns sigmoidal contrast-enhanced weight from linear weight,
// centered at 1 and normed in range +/- 1 around that
// in preparation for multiplying times SWt
func (sp *SWtParams) SigFromLinWt(lw float32) float32 {
	var wt float32
	if sp.Adapt.SigGain == 1 {
		wt = lw
	} else if sp.Adapt.SigGain == 6 {
		wt = SigFun61(lw)
	} else {
		wt = SigFun(lw, sp.Adapt.SigGain, 1)
	}
	return 2.0 * wt // center at 1 instead of .5
}

// LinFromSigWt returns linear weight from sigmoidal contrast-enhanced weight.
// wt is centered at 1, and normed in range +/- 1 around that,
// return value is in 0-1 range, centered at .5
func (sp *SWtParams) LinFromSigWt(wt float32) float32 {
	wte := wt * 0.5
	if wte < 0 {
		wte = 0
	} else if wte > 1 {
		wte = 1
	}
	if sp.Adapt.SigGain == 1 {
		return wte
	}
	if sp.Adapt.SigGain == 6 {
		return SigInvFun61(wte)
	}
	return SigInvFun(wte, sp.Adapt.SigGain, 1)
}

// LWtFromWts returns linear, learning LWt from wt and swt.
// LWt is set to reproduce given Wt relative to given SWt base value.
func (sp *SWtParams) LWtFromWts(wt, swt float32) float32 {
	rwt := wt / swt
	return sp.LinFromSigWt(rwt)
}

// WtFromDWt updates the synaptic weights from accumulated weight changes.
// wt is the sigmoidal contrast-enhanced weight and lwt is the linear weight value.
func (sp *SWtParams) WtFromDWt(wt, lwt *float32, dwt, swt float32) {
	if dwt == 0 {
		if *wt == 0 { // restore failed wts
			*wt = sp.WtValue(swt, *lwt)
		}
		return
	}
	// note: softbound happened at dwt stage
	*lwt += dwt
	if *lwt < 0 {
		*lwt = 0
	} else if *lwt > 1 {
		*lwt = 1
	}
	*wt = sp.WtValue(swt, *lwt)
}

//gosl:end

// RandVar returns the random variance in weight value (zero mean) based on Var param
func (sp *SWtInitParams) RandVar(rnd randx.Rand) float32 {
	return sp.Var * 2.0 * (rnd.Float32() - 0.5)
}

// // RandVar returns the random variance (zero mean) based on DreamVar param
// func (sp *SWtAdaptParams) RandVar(rnd randx.Rand) float32 {
// 	return sp.DreamVar * 2.0 * (rnd.Float32(-1) - 0.5)
// }

// InitWeightsSyn initializes weight values based on WtInit randomness parameters
// for an individual synapse.
// It also updates the linear weight value based on the sigmoidal weight value.
func (sp *SWtParams) InitWeightsSyn(ctx *Context, syni uint32, rnd randx.Rand, mean, spct float32) {
	wtv := sp.Init.RandVar(rnd)
	wt := mean + wtv
	Synapses[syni, Wt] = wt
	Synapses[syni, SWt] = sp.ClipSWt(mean + spct*wtv)
	if spct == 0 { // this is critical for weak init wt, SPCt = 0 paths
		Synapses[syni, SWt] = 0.5
	}
	Synapses[syni, LWt] = sp.LWtFromWts(wt, Synapses[syni, SWt])
	Synapses[syni, DWt] = 0
	Synapses[syni, DSWt] = 0
}

// InitWeightsSynTrace initializes SynapseTrace values
// for an individual synapse.
func (sp *SWtParams) InitWeightsSynTrace(ctx *Context, syni, di uint32) {
	SynapseTraces[syni, di, Tr] = 0
	SynapseTraces[syni, di, DTr] = 0
	SynapseTraces[syni, di, DiDWt] = 0
}

//gosl:start

// LRateParams manages learning rate parameters for scaling [DWt] delta
// weight values that then update [LWt] online learned weights.
// It has two optional modulation factors on top of a Base learning rate.
type LRateParams struct {

	// Base learning rate for this pathway, which can be modulated
	// by the other factors below. Generally larger networks use slower rates.
	Base float32 `default:"0.04,0.1,0.2"`

	// Sched is a scheduled learning rate multiplier, simulating reduction
	// in plasticity over aging. Use the [Network.LRateSched] method to apply
	// a given value to all pathways in the network.
	Sched float32

	// Mod is a dynamic learning rate modulation factor, typically driven by
	// neuromodulation (e.g., dopamine).
	Mod float32

	// Eff is the net effective actual learning rate multiplier used in
	// computing [DWt]: Eff = Mod * Sched * Base
	Eff float32 `edit:"-"`
}

func (ls *LRateParams) Defaults() {
	ls.Base = 0.04
	ls.Sched = 1
	ls.Mod = 1
	ls.Update()
}

func (ls *LRateParams) Update() {
	ls.UpdateEff()
}

func (ls *LRateParams) UpdateEff() {
	ls.Eff = ls.Mod * ls.Sched * ls.Base
}

// Init initializes modulation values back to 1 and updates Eff
func (ls *LRateParams) Init() {
	ls.Sched = 1
	ls.Mod = 1
	ls.UpdateEff()
}

//////// DWtParams

// DWtParams has misc parameters for computing weight changes ([DWt]) for the default
// kinase trace-based error-driven cortical learning rule, and for other specialized
// learning rules.
type DWtParams struct {

	// Trace uses the default trace-based version of the kinase error-driven cortical
	// learning algorithm, where the per-trial error delta is computed from
	// [LearnCaP] - [LearnCaD], and the credit assignment factor is computed from the
	// synaptic product of [CaSyn], integrated over [CaBins] separately on the
	// sender and receiver neurons, which are then multiplied at each synapse and
	// integrated to efficiently compute synaptic CaP and CaD factors.
	// This synaptic CaD is integrated across theta cycle trials with the Tau
	// parameter to produce the final multiplicative credit assignment factor.
	// If Trace = false, then the synaptic CaP - CaD delta is used directly as
	// the error-driven learning signal, precluding the longer-timescale trace
	// integration factor (Trace = false is automatically used for Target layers).
	Trace slbool.Bool `default:"true"`

	// Tau is the time constant for integrating the synaptic trace [Tr]
	// over the theta cycle learning timescale. Larger values (greater than 1)
	// produce longer time windows of integration, and should only be used when
	// there is temporal structure to be learned across these longer timescales.
	Tau float32 `default:"1,2,4"`

	// CaScale is a multiplier on the total synaptic calcium values, computed from products
	// of the neuron-level [CaBins] values. If [Context.CaBinCycles] is lower than
	// default of 25, then this value needs to be set higher, e.g., 2 for cycles = 10.
	CaScale float32 `default:"1"`

	// CaPScale is a separate multiplier for the CaP component of synaptic calcium, to
	// allow separate weighting of potentiation (CaP) vs. depression (CaD) factors.
	CaPScale float32 `default:"1"`

	// SubMean is the amount of the mean [dWt] to subtract for updating the online
	// learning [LWt] values, producing a zero-sum effect. 1.0 = full zero-sum dWt.
	// Only applies to non-zero DWts. There is a separate such factor for [SWt].
	// Typically set to 0 for standard trace learning pathways, although some require it
	// for stability over the long haul. Can use [Network.SetSubMean] to set to 1 after
	// significant early learning has occurred with 0.
	// Some special path types (e.g., Hebb) benefit from SubMean = 1 always.
	SubMean float32 `default:"0,1"`

	// LearnThr is the threshold for learning, for specialized learning algorithms.
	// This is not relevant for the standard kinase error-driven cortical learning algorithm.
	// In Matrix and VSPatch it applies to normalized GeIntNorm value: setting this relatively
	// high encourages sparser representations.
	LearnThr float32

	// Dt rate = 1 / tau
	Dt float32 `display:"-" json:"-" xml:"-" edit:"-"`

	pad float32
}

func (tp *DWtParams) Defaults() {
	tp.Trace.SetBool(true)
	tp.Tau = 1
	tp.CaScale = 1
	tp.CaPScale = 1
	tp.SubMean = 0
	tp.LearnThr = 0
	tp.Update()
}

func (tp *DWtParams) Update() {
	tp.Dt = 1.0 / tp.Tau
}

// TrFromCa returns updated trace factor as function of a
// synaptic calcium update factor and current trace
func (tp *DWtParams) TrFromCa(tr float32, ca float32) float32 {
	return tr + tp.Dt*(ca-tr)
}

////////  HebbParams

// HebbParams for optional hebbian learning that replaces the
// default learning rule, based on S = sending activity,
// R = receiving activity
type HebbParams struct {

	// On turns on the use of the Hebbian learning rule instead of the default.
	On slbool.Bool

	// Up is the strength multiplier for hebbian increases, based on R * S * (1-LWt).
	Up float32 `default:"0.5"`

	// Down is the strength multiplier for hebbian decreases, based on R * (1 - S) * LWt.
	Down float32 `default:"1"`

	pad float32
}

func (hp *HebbParams) Defaults() {
	hp.Up = 0.5
	hp.Down = 1
}

func (hp *HebbParams) Update() {
}

func (hp *HebbParams) ShouldDisplay(field string) bool {
	switch field {
	case "On":
		return true
	default:
		return hp.On.IsTrue()
	}
}

////////  LearnSynParams

// LearnSynParams manages learning-related parameters at the synapse-level.
type LearnSynParams struct {

	// Learn enables learning for this pathway.
	Learn slbool.Bool

	pad, pad1, pad2 int32

	// LRateParams manages learning rate parameters for scaling [DWt] delta
	// weight values that then update [LWt] online learned weights.
	// It has two optional modulation factors on top of a Base learning rate.
	LRate LRateParams `display:"inline"`

	// DWtParams has misc parameters for computing weight changes ([DWt]) for the default
	// trace-based cortical learning rule and for other specialized learning rules.
	DWt DWtParams `display:"inline"`

	// hebbian learning option, which overrides the default learning rules
	Hebb HebbParams `display:"inline"`
}

func (ls *LearnSynParams) Update() {
	ls.LRate.Update()
	ls.DWt.Update()
	ls.Hebb.Update()
}

func (ls *LearnSynParams) Defaults() {
	ls.Learn.SetBool(true)
	ls.LRate.Defaults()
	ls.DWt.Defaults()
	ls.Hebb.Defaults()
}

func (ls *LearnSynParams) ShouldDisplay(field string) bool {
	switch field {
	case "Learn":
		return true
	default:
		return ls.Learn.IsTrue()
	}
}

// CHLdWt returns the error-driven weight change component for a
// CHL contrastive hebbian learning rule, optionally using the checkmark
// temporally eXtended Contrastive Attractor Learning (XCAL) function
func (ls *LearnSynParams) CHLdWt(suCaP, suCaD, ruCaP, ruCaD float32) float32 {
	srp := suCaP * ruCaP
	srd := suCaD * ruCaD
	return srp - srd
}

// DeltaDWt returns the error-driven weight change component for a
// simple delta between a minus and plus phase factor, optionally using the checkmark
// temporally eXtended Contrastive Attractor Learning (XCAL) function
func (ls *LearnSynParams) DeltaDWt(plus, minus float32) float32 {
	return plus - minus
}

//gosl:end

////////  LRateMod

// LRateMod implements global learning rate modulation, based on a performance-based
// factor, for example error. Increasing levels of the factor = higher learning rate.
// This can be added to a Sim and called prior to DWt() to dynamically change lrate
// based on overall network performance. It is not used by default in the standard params.
type LRateMod struct {

	// toggle use of this modulation factor
	On slbool.Bool

	// baseline learning rate -- what you get for correct cases
	Base float32 `min:"0" max:"1"`

	pad, pad1 int32

	// defines the range over which modulation occurs for the modulator factor -- Min and below get the Base level of learning rate modulation, Max and above get a modulation of 1
	Range minmax.F32
}

func (lr *LRateMod) Defaults() {
	lr.On.SetBool(true)
	lr.Base = 0.2
	lr.Range.Set(0.2, 0.8)
}

func (lr *LRateMod) Update() {
}

func (lr *LRateMod) ShouldDisplay(field string) bool {
	switch field {
	case "On":
		return true
	default:
		return lr.On.IsTrue()
	}
}

// Mod returns the learning rate modulation factor as a function
// of any kind of normalized modulation factor, e.g., an error measure.
// If fact <= Range.Min, returns Base
// If fact >= Range.Max, returns 1
// otherwise, returns proportional value between Base..1
func (lr *LRateMod) Mod(fact float32) float32 {
	lrm := lr.Range.NormValue(fact) // clips to 0-1 range
	md := lr.Base + lrm*(1-lr.Base) // resulting mod is in Base-1 range
	return md
}

// LRateMod calls LRateMod on given network, using computed Mod factor
// based on given normalized modulation factor
// (0 = no error = Base learning rate, 1 = maximum error).
// returns modulation factor applied.
func (lr *LRateMod) LRateMod(net *Network, fact float32) float32 {
	if lr.Range.Max == 0 {
		lr.Defaults()
	}
	if lr.On.IsFalse() {
		return 1
	}
	md := lr.Mod(fact)
	net.LRateMod(md)
	return md
}