params

package
v1.4.31 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 27, 2023 License: BSD-3-Clause Imports: 18 Imported by: 160

README

Docs: GoDoc

See Wiki Params page for detailed docs.

Package params provides general-purpose parameter management functionality for organizing multiple sets of parameters efficiently, and basic IO for saving / loading from JSON files and generating Go code to embed into applications, and a basic GUI for viewing and editing.

IMPORTANT: as of July, 2023, params has been deprecated in favor of netparams which is focused only on Network params, for which the styling and structure of this params system makes the most sense. Use econfig for setting params on standard struct objects such as Config structs.

The main overall unit that is generally operated upon at run-time is the params.Set, which is a collection of params.Sheet's (akin to CSS style sheets) that constitute a coherent set of parameters. Here's the structure:

Sets {
    Set: "Base" {
        Sheets {
            "Network": {
                Sel: "Layer" {
                    Params: {
                        "Layer.Inhib.Layer.Gi": "1.1",
                        ...
                    }
                },
                Sel: ".Back" {
                    Params: {
                        "Prjn.PrjnScale.Rel": "0.2",
                        ...
                    }
                }
            },
            "Sim": {
                ...
            }
        }
    },
    Set: "Option1" {
        ...
    }
}        

A good strategy is to have a "Base" Set that has all the best parameters so far, and then other sets can modify specific params relative to that one. Order of application is critical, as subsequent params applications overwrite earlier ones, and the typical order is:

  • Defaults() method called that establishes the hard-coded default parameters.
  • Then apply "Base" params.Set for any changes relative to those.
  • Then optionally apply one or more additional params.Set's with current experimental parameters.

Critically, all of this is entirely up to the particular model program(s) to determine and control -- this package just provides the basic data structures for holding all of the parameters, and the IO / and Apply infrastructure.

Within a params.Set, multiple different params.Sheet's can be organized, with each CSS-style sheet achieving a relatively complete parameter styling of a given element of the overal model, e.g., "Network", "Sim", "Env". Or Network could be further broken down into "Learn" vs. "Act" etc, or according to different brain areas ("Hippo", "PFC", "BG", etc). Again, this is entirely at the discretion of the modeler and must be performed under explict program control, especially because order is so critical.

Each params.Sheet consists of a collection of params.Sel elements which actually finally contain the parameters. The Sel field specifies a CSS-style selector determining over what scope the parameters should be applied:

  • Type (no prefix) = name of a type -- anything having this type name will get these params.

  • .Class = anything with a given class label (each object can have multiple Class labels and thus receive multiple parameter settings, but again, order matters!)

  • #Name = a specific named object.

The order of application within a given Sheet is also critical -- typically put the most general Type params first, then .Class, then the most specific #Name cases, to achieve within a given Sheet the same logic of establishing Base params for all types and then more specific overrides for special cases (e.g., an overall learning rate that appplies across all projections, but maybe a faster or slower one for a .Class or specific #Name'd projection).

There is a params.Styler interface with methods that any Go type can implement to provide these different labels. The emer.Network, .Layer, and .Prjn interfaces each implement this interface.

Otherwise, the Apply method will just directly apply params to a given struct type if it does not implement the Styler interface.

Parameter values are stored as strings, which can represent any value.

Finally, there are methods to show where params.Set's set the same parameter differently, and to compare with the default settings on a given object type using go struct field tags of the form def:"val1[,val2...]".

Providing direct access to specific params

The best way to provide the user direct access to specific parameter values through the Params mechanisms is to put the relevant params in the Sim object, where they will be editable fields, and then call SetFloat or SetString as appropriate with the path to the parameter in question, followed by a call to apply the params.

The current value can be obtained by the ParamVal methods.

Documentation

Overview

Package params provides general-purpose parameter management functionality for organizing multiple sets of parameters efficiently, and basic IO for saving / loading from JSON files and generating Go code to embed into applications, and a basic GUI for viewing and editing.

The main overall unit that is generally operated upon at run-time is the params.Set, which is a collection of params.Sheet's (akin to CSS style sheets) that constitute a coherent set of parameters.

A good strategy is to have a "Base" Set that has all the best parameters so far, and then other sets can modify specific params relative to that one. Order of application is critical, as subsequent params applications overwrite earlier ones, and the typical order is:

  • Defaults() method called that establishes the hard-coded default parameters.
  • Then apply "Base" params.Set for any changes relative to those.
  • Then optionally apply one or more additional params.Set's with current experimental parameters.

Critically, all of this is entirely up to the particular model program(s) to determine and control -- this package just provides the basic data structures for holding all of the parameters, and the IO / and Apply infrastructure.

Within a params.Set, multiple different params.Sheet's can be organized, with each CSS-style sheet achieving a relatively complete parameter styling of a given element of the overal model, e.g., "Network", "Sim", "Env". Or Network could be further broken down into "Learn" vs. "Act" etc, or according to different brain areas ("Hippo", "PFC", "BG", etc). Again, this is entirely at the discretion of the modeler and must be performed under explict program control, especially because order is so critical.

Each params.Sheet consists of a collection of params.Sel elements which actually finally contain the parameters. The Sel field specifies a CSS-style selector determining over what scope the parameters should be applied:

* Type = name of a type -- anything having this type name will get these params.

* .Class = anything with a given class label (each object can have multiple Class labels and thus receive multiple parameter settings, but again, order matters!)

* #Name = a specific named object.

The order of application within a given Sheet is also critical -- typically put the most general Type params first, then .Class, then the most specific #Name cases, to achieve within a given Sheet the same logic of establishing Base params for all types and then more specific overrides for special cases (e.g., an overall learning rate that appplies across all projections, but maybe a faster or slower one for a .Class or specific #Name'd projection).

There is a params.Styler interface with methods that any Go type can implement to provide these different labels. The emer.Network, .Layer, and .Prjn interfaces each implement this interface.

Otherwise, the Apply method will just directly apply params to a given struct type if it does not implement the Styler interface.

Parameter values are limited to float64 values *only*. These can be specified using "enum" style const integer values, and can be applied to any numeric type (they will be automatically converted), but internally this is the only parameter value type, which greatly simplifies the overall interface, and handles the vast majority of use-cases (especially because named options are just integers and can be set as such).

Finally, there are methods to show where params.Set's set the same parameter differently, and to compare with the default settings on a given object type using go struct field tags of the form def:"val1[,val2...]".

Index

Constants

This section is empty.

Variables

View Source
var HypersProps = ki.Props{
	"ToolBar": ki.PropSlice{
		{"Save", ki.PropSlice{
			{"SaveTOML", ki.Props{
				"label": "Save As TOML...",
				"desc":  "save to TOML formatted file",
				"icon":  "file-save",
				"Args": ki.PropSlice{
					{"File Name", ki.Props{
						"ext": ".toml",
					}},
				},
			}},
			{"SaveJSON", ki.Props{
				"label": "Save As JSON...",
				"desc":  "save to JSON formatted file",
				"icon":  "file-save",
				"Args": ki.PropSlice{
					{"File Name", ki.Props{
						"ext": ".json",
					}},
				},
			}},
			{"SaveGoCode", ki.Props{
				"label": "Save Code As...",
				"desc":  "save to Go-formatted initializer code in file",
				"icon":  "go",
				"Args": ki.PropSlice{
					{"File Name", ki.Props{
						"ext": ".go",
					}},
				},
			}},
		}},
		{"Open", ki.PropSlice{
			{"OpenTOML", ki.Props{
				"label": "Open...",
				"desc":  "open from TOML formatted file",
				"icon":  "file-open",
				"Args": ki.PropSlice{
					{"File Name", ki.Props{
						"ext": ".toml",
					}},
				},
			}},
			{"OpenJSON", ki.Props{
				"label": "Open...",
				"desc":  "open from JSON formatted file",
				"icon":  "file-open",
				"Args": ki.PropSlice{
					{"File Name", ki.Props{
						"ext": ".json",
					}},
				},
			}},
		}},
		{"StringGoCode", ki.Props{
			"label":       "Show Code",
			"desc":        "shows the Go-formatted initializer code, can be copy / pasted into program",
			"icon":        "go",
			"show-return": true,
		}},
	},
}
View Source
var KiT_Hypers = kit.Types.AddType(&Hypers{}, HypersProps)
View Source
var KiT_Params = kit.Types.AddType(&Params{}, ParamsProps)
View Source
var KiT_Sel = kit.Types.AddType(&Sel{}, SelProps)
View Source
var KiT_Set = kit.Types.AddType(&Set{}, SetProps)
View Source
var KiT_Sets = kit.Types.AddType(&Sets{}, SetsProps)
View Source
var KiT_Sheet = kit.Types.AddType(&Sheet{}, SheetProps)
View Source
var KiT_Sheets = kit.Types.AddType(&Sheets{}, SheetsProps)
View Source
var ParamsProps = ki.Props{
	"ToolBar": ki.PropSlice{
		{"Save", ki.PropSlice{
			{"SaveTOML", ki.Props{
				"label": "Save As TOML...",
				"desc":  "save to TOML formatted file",
				"icon":  "file-save",
				"Args": ki.PropSlice{
					{"File Name", ki.Props{
						"ext": ".toml",
					}},
				},
			}},
			{"SaveJSON", ki.Props{
				"label": "Save As JSON...",
				"desc":  "save to JSON formatted file",
				"icon":  "file-save",
				"Args": ki.PropSlice{
					{"File Name", ki.Props{
						"ext": ".json",
					}},
				},
			}},
			{"SaveGoCode", ki.Props{
				"label": "Save Code As...",
				"desc":  "save to Go-formatted initializer code in file",
				"icon":  "go",
				"Args": ki.PropSlice{
					{"File Name", ki.Props{
						"ext": ".go",
					}},
				},
			}},
		}},
		{"Open", ki.PropSlice{
			{"OpenTOML", ki.Props{
				"label": "Open...",
				"desc":  "open from TOML formatted file",
				"icon":  "file-open",
				"Args": ki.PropSlice{
					{"File Name", ki.Props{
						"ext": ".toml",
					}},
				},
			}},
			{"OpenJSON", ki.Props{
				"label": "Open...",
				"desc":  "open from JSON formatted file",
				"icon":  "file-open",
				"Args": ki.PropSlice{
					{"File Name", ki.Props{
						"ext": ".json",
					}},
				},
			}},
		}},
		{"StringGoCode", ki.Props{
			"label":       "Show Code",
			"desc":        "shows the Go-formatted initializer code, can be copy / pasted into program",
			"icon":        "go",
			"show-return": true,
		}},
	},
}
View Source
var SelProps = ki.Props{
	"ToolBar": ki.PropSlice{
		{"Save", ki.PropSlice{
			{"SaveTOML", ki.Props{
				"label": "Save As TOML...",
				"desc":  "save to TOML formatted file",
				"icon":  "file-save",
				"Args": ki.PropSlice{
					{"File Name", ki.Props{
						"ext": ".toml",
					}},
				},
			}},
			{"SaveJSON", ki.Props{
				"label": "Save As JSON...",
				"desc":  "save to JSON formatted file",
				"icon":  "file-save",
				"Args": ki.PropSlice{
					{"File Name", ki.Props{
						"ext": ".json",
					}},
				},
			}},
			{"SaveGoCode", ki.Props{
				"label": "Save Code As...",
				"desc":  "save to Go-formatted initializer code in file",
				"icon":  "go",
				"Args": ki.PropSlice{
					{"File Name", ki.Props{
						"ext": ".go",
					}},
				},
			}},
		}},
		{"Open", ki.PropSlice{
			{"OpenTOML", ki.Props{
				"label": "Open...",
				"desc":  "open from TOML formatted file",
				"icon":  "file-open",
				"Args": ki.PropSlice{
					{"File Name", ki.Props{
						"ext": ".toml",
					}},
				},
			}},
			{"OpenJSON", ki.Props{
				"label": "Open...",
				"desc":  "open from JSON formatted file",
				"icon":  "file-open",
				"Args": ki.PropSlice{
					{"File Name", ki.Props{
						"ext": ".json",
					}},
				},
			}},
		}},
		{"StringGoCode", ki.Props{
			"label":       "Show Code",
			"desc":        "shows the Go-formatted initializer code, can be copy / pasted into program",
			"icon":        "go",
			"show-return": true,
		}},
	},
}
View Source
var SetProps = ki.Props{
	"ToolBar": ki.PropSlice{
		{"Save", ki.PropSlice{
			{"SaveTOML", ki.Props{
				"label": "Save As TOML...",
				"desc":  "save to TOML formatted file",
				"icon":  "file-save",
				"Args": ki.PropSlice{
					{"File Name", ki.Props{
						"ext": ".toml",
					}},
				},
			}},
			{"SaveJSON", ki.Props{
				"label": "Save As JSON...",
				"desc":  "save to JSON formatted file",
				"icon":  "file-save",
				"Args": ki.PropSlice{
					{"File Name", ki.Props{
						"ext": ".json",
					}},
				},
			}},
		}},
		{"Open", ki.PropSlice{
			{"OpenTOML", ki.Props{
				"label": "Open...",
				"desc":  "open from TOML formatted file",
				"icon":  "file-open",
				"Args": ki.PropSlice{
					{"File Name", ki.Props{
						"ext": ".toml",
					}},
				},
			}},
			{"OpenJSON", ki.Props{
				"label": "Open...",
				"desc":  "open from JSON formatted file",
				"icon":  "file-open",
				"Args": ki.PropSlice{
					{"File Name", ki.Props{
						"ext": ".json",
					}},
				},
			}},
		}},
		{"sep-diffs", ki.BlankProp{}},
		{"DiffsWithin", ki.Props{
			"desc":        "reports where the same param path is being set to different values within this set (both within the same Sheet and betwen sheets)",
			"icon":        "search",
			"show-return": true,
		}},
	},
}
View Source
var SetsProps = ki.Props{
	"ToolBar": ki.PropSlice{
		{"Save", ki.PropSlice{
			{"SaveTOML", ki.Props{
				"label": "Save As TOML...",
				"desc":  "save to TOML formatted file",
				"icon":  "file-save",
				"Args": ki.PropSlice{
					{"File Name", ki.Props{
						"ext": ".toml",
					}},
				},
			}},
			{"SaveJSON", ki.Props{
				"label": "Save As JSON...",
				"desc":  "save to JSON formatted file",
				"icon":  "file-save",
				"Args": ki.PropSlice{
					{"File Name", ki.Props{
						"ext": ".json",
					}},
				},
			}},
			{"SaveGoCode", ki.Props{
				"label": "Save Code As...",
				"desc":  "save to Go-formatted initializer code in file",
				"icon":  "go",
				"Args": ki.PropSlice{
					{"File Name", ki.Props{
						"ext": ".go",
					}},
				},
			}},
		}},
		{"Open", ki.PropSlice{
			{"OpenTOML", ki.Props{
				"label": "Open...",
				"desc":  "open from TOML formatted file",
				"icon":  "file-open",
				"Args": ki.PropSlice{
					{"File Name", ki.Props{
						"ext": ".toml",
					}},
				},
			}},
			{"OpenJSON", ki.Props{
				"label": "Open...",
				"desc":  "open from JSON formatted file",
				"icon":  "file-open",
				"Args": ki.PropSlice{
					{"File Name", ki.Props{
						"ext": ".json",
					}},
				},
			}},
		}},
		{"StringGoCode", ki.Props{
			"label":       "Show Code",
			"desc":        "shows the Go-formatted initializer code, can be copy / pasted into program",
			"icon":        "go",
			"show-return": true,
		}},
		{"sep-diffs", ki.BlankProp{}},
		{"DiffsAll", ki.Props{
			"desc":        "between all sets, reports where the same param path is being set to different values",
			"icon":        "search",
			"show-return": true,
		}},
		{"DiffsFirst", ki.Props{
			"desc":        "between first set (e.g., the Base set) and rest of sets, reports where the same param path is being set to different values",
			"icon":        "search",
			"show-return": true,
		}},
		{"DiffsWithin", ki.Props{
			"desc":        "reports all the cases where the same param path is being set to different values within different sheets in given set",
			"icon":        "search",
			"show-return": true,
			"Args": ki.PropSlice{
				{"Set Name", ki.Props{}},
			},
		}},
	},
}
View Source
var SheetProps = ki.Props{
	"ToolBar": ki.PropSlice{
		{"Save", ki.PropSlice{
			{"SaveTOML", ki.Props{
				"label": "Save As TOML...",
				"desc":  "save to TOML formatted file",
				"icon":  "file-save",
				"Args": ki.PropSlice{
					{"File Name", ki.Props{
						"ext": ".toml",
					}},
				},
			}},
			{"SaveJSON", ki.Props{
				"label": "Save As JSON...",
				"desc":  "save to JSON formatted file",
				"icon":  "file-save",
				"Args": ki.PropSlice{
					{"File Name", ki.Props{
						"ext": ".json",
					}},
				},
			}},
			{"SaveGoCode", ki.Props{
				"label": "Save Code As...",
				"desc":  "save to Go-formatted initializer code in file",
				"icon":  "go",
				"Args": ki.PropSlice{
					{"File Name", ki.Props{
						"ext": ".go",
					}},
				},
			}},
		}},
		{"Open", ki.PropSlice{
			{"OpenTOML", ki.Props{
				"label": "Open...",
				"desc":  "open from TOML formatted file",
				"icon":  "file-open",
				"Args": ki.PropSlice{
					{"File Name", ki.Props{
						"ext": ".toml",
					}},
				},
			}},
			{"OpenJSON", ki.Props{
				"label": "Open...",
				"desc":  "open from JSON formatted file",
				"icon":  "file-open",
				"Args": ki.PropSlice{
					{"File Name", ki.Props{
						"ext": ".json",
					}},
				},
			}},
		}},
		{"StringGoCode", ki.Props{
			"label":       "Show Code",
			"desc":        "shows the Go-formatted initializer code, can be copy / pasted into program",
			"icon":        "go",
			"show-return": true,
		}},
	},
}
View Source
var SheetsProps = ki.Props{
	"ToolBar": ki.PropSlice{
		{"Save", ki.PropSlice{
			{"SaveTOML", ki.Props{
				"label": "Save As TOML...",
				"desc":  "save to TOML formatted file",
				"icon":  "file-save",
				"Args": ki.PropSlice{
					{"File Name", ki.Props{
						"ext": ".toml",
					}},
				},
			}},
			{"SaveJSON", ki.Props{
				"label": "Save As JSON...",
				"desc":  "save to JSON formatted file",
				"icon":  "file-save",
				"Args": ki.PropSlice{
					{"File Name", ki.Props{
						"ext": ".json",
					}},
				},
			}},
			{"SaveGoCode", ki.Props{
				"label": "Save Code As...",
				"desc":  "save to Go-formatted initializer code in file",
				"icon":  "go",
				"Args": ki.PropSlice{
					{"File Name", ki.Props{
						"ext": ".go",
					}},
				},
			}},
		}},
		{"Open", ki.PropSlice{
			{"OpenTOML", ki.Props{
				"label": "Open...",
				"desc":  "open from TOML formatted file",
				"icon":  "file-open",
				"Args": ki.PropSlice{
					{"File Name", ki.Props{
						"ext": ".toml",
					}},
				},
			}},
			{"OpenJSON", ki.Props{
				"label": "Open...",
				"desc":  "open from JSON formatted file",
				"icon":  "file-open",
				"Args": ki.PropSlice{
					{"File Name", ki.Props{
						"ext": ".json",
					}},
				},
			}},
		}},
		{"StringGoCode", ki.Props{
			"label":       "Show Code",
			"desc":        "shows the Go-formatted initializer code, can be copy / pasted into program",
			"icon":        "go",
			"show-return": true,
		}},
		{"sep-diffs", ki.BlankProp{}},
		{"DiffsWithin", ki.Props{
			"desc":        "reports where the same param path is being set to different values within this set (both within the same Sheet and betwen sheets)",
			"icon":        "search",
			"show-return": true,
		}},
	},
}

Functions

func AddClass added in v1.4.11

func AddClass(cur, class string) string

AddClass adds given class to current class string, ensuring it is not a duplicate of existing, and properly adding spaces

func ApplyMap added in v1.4.11

func ApplyMap(obj any, vals map[string]any, setMsg bool) error

ApplyMap applies given map[string]any values, where the map keys are a Path and the value is the value to apply (any appropriate type). This is not for Network params, which should use MapToSheet -- see emer.Params wrapper. If setMsg is true, then a message is printed to confirm each parameter that is set. It always prints a message if a parameter fails to be set, and returns an error.

func ClassMatch

func ClassMatch(sel, cls string) bool

ClassMatch returns true if given class names. handles space-separated multiple class names

func FindParam

func FindParam(val reflect.Value, path string) (reflect.Value, error)

FindParam parses the path and recursively tries to find the parameter pointed to by the path (dot-delimited field names). Returns error if not found, and always also emits error messages -- the target type should already have been identified and this should only be called when there is an expectation of the path working.

func GetParam

func GetParam(obj any, path string) (float64, error)

GetParam gets parameter value at given path on given object. converts target type to float64. returns error if path not found or target is not a numeric type (always logged).

func SelMatch

func SelMatch(sel string, name, cls, styp, gotyp string) bool

SelMatch returns true if Sel selector matches the target object properties

func SetParam

func SetParam(obj any, path string, val string) error

SetParam sets parameter at given path on given object to given value converts the string param val as appropriate for target type. returns error if path not found or cannot set (always logged).

func WriteGoPrelude

func WriteGoPrelude(w io.Writer, varNm string)

WriteGoPrelude writes the start of a go file in package main that starts a variable assignment to given variable -- for start of SaveGoCode methods.

Types

type Flex added in v1.1.51

type Flex map[string]*FlexVal

Flex supports arbitrary named parameter values that can be set by a Set of parameters, as a map of any objects. First initialize the map with set of names and a type to create blank values, then apply the Set to it.

func (*Flex) ApplySheet added in v1.1.51

func (fl *Flex) ApplySheet(sheet *Sheet, setMsg bool)

ApplySheet applies given sheet of parameters to each element in Flex

func (*Flex) Class added in v1.1.51

func (fl *Flex) Class() string

func (*Flex) CopyFrom added in v1.1.51

func (fl *Flex) CopyFrom(cp Flex)

CopyFrom copies hyper vals from source

func (*Flex) Init added in v1.1.51

func (fl *Flex) Init(vals []FlexVal)

Init initializes the Flex map with given set of flex values.

func (*Flex) JSONString added in v1.1.51

func (fl *Flex) JSONString() string

JSONString returns a string representation of Flex params

func (*Flex) Make added in v1.1.51

func (fl *Flex) Make()

Make makes the map if it is nil (otherwise does nothing)

func (*Flex) Name added in v1.1.51

func (fl *Flex) Name() string

func (*Flex) SaveJSON added in v1.1.51

func (fl *Flex) SaveJSON(filename gi.FileName) error

SaveJSON saves hypers to a JSON-formatted file.

func (*Flex) TypeName added in v1.1.51

func (fl *Flex) TypeName() string

func (*Flex) WriteJSON added in v1.1.51

func (fl *Flex) WriteJSON(w io.Writer) error

WriteJSON saves hypers to a JSON-formatted file.

type FlexVal added in v1.1.51

type FlexVal struct {

	// name of this specific object -- matches #Name selections
	Nm string `desc:"name of this specific object -- matches #Name selections"`

	// type name of this object -- matches plain TypeName selections
	Type string `desc:"type name of this object -- matches plain TypeName selections"`

	// space-separated list of class name(s) -- match the .Class selections
	Cls string `desc:"space-separated list of class name(s) -- match the .Class selections"`

	// actual object with data that is set by the parameters
	Obj any `desc:"actual object with data that is set by the parameters"`
}

FlexVal is a specific flexible value for the Flex parameter map that implements the StylerObj interface for CSS-style selection logic

func (*FlexVal) Class added in v1.1.51

func (fv *FlexVal) Class() string

func (*FlexVal) CopyFrom added in v1.1.51

func (fv *FlexVal) CopyFrom(cp *FlexVal)

func (*FlexVal) Name added in v1.1.51

func (fv *FlexVal) Name() string

func (*FlexVal) Object added in v1.1.51

func (fv *FlexVal) Object() any

func (*FlexVal) TypeName added in v1.1.51

func (fv *FlexVal) TypeName() string

type History added in v1.3.46

type History interface {
	// ParamsHistoryReset resets parameter application history
	ParamsHistoryReset()

	// ParamsApplied is called when a parameter is successfully applied for given selector
	ParamsApplied(sel *Sel)
}

The params.History interface records history of parameters applied to a given object.

type HistoryImpl added in v1.3.46

type HistoryImpl []*Sel

HistoryImpl implements the History interface. Implementing object can just pass calls to a HistoryImpl field.

func (*HistoryImpl) ParamsApplied added in v1.3.46

func (hi *HistoryImpl) ParamsApplied(sel *Sel)

ParamsApplied is called when a parameter is successfully applied for given selector

func (*HistoryImpl) ParamsHistory added in v1.3.46

func (hi *HistoryImpl) ParamsHistory() Params

ParamsHistory returns the sequence of params applied for each parameter from all Sel's applied, in reverse order

func (*HistoryImpl) ParamsHistoryReset added in v1.3.46

func (hi *HistoryImpl) ParamsHistoryReset()

ParamsHistoryReset resets parameter application history

type HyperVals added in v1.1.51

type HyperVals map[string]string

HyperVals is a string-value map for storing hyperparameter values

func (*HyperVals) CopyFrom added in v1.1.51

func (hv *HyperVals) CopyFrom(cp HyperVals)

CopyFrom copies from another HyperVals

func (*HyperVals) JSONString added in v1.1.51

func (hv *HyperVals) JSONString() string

JSONString returns hyper values as a JSON formatted string

func (*HyperVals) SetJSONString added in v1.1.51

func (hv *HyperVals) SetJSONString(str string) error

SetJSONString sets from a JSON_formatted string

type Hypers added in v1.1.50

type Hypers map[string]HyperVals

Hypers is a parallel structure to Params which stores information relevant to hyperparameter search as well as the values. Use the key "Val" for the default value. This is equivalant to the value in Params. "Min" and "Max" guid the range, and "Sigma" describes a Gaussian.

func (*Hypers) Apply added in v1.1.50

func (pr *Hypers) Apply(obj any, setMsg bool) error

Apply applies all parameter values to given object. Object must already be the appropriate target type based on the first element of the path (see TargetType method). If setMsg is true, then it will log a confirmation that the parameter was set (it always prints an error message if it fails to set the parameter at given path, and returns error if so).

func (*Hypers) CopyFrom added in v1.1.51

func (pr *Hypers) CopyFrom(cp Hypers)

CopyFrom copies hyper vals from source

func (*Hypers) DeleteValOnly added in v1.1.51

func (pr *Hypers) DeleteValOnly()

DeleteValOnly deletes entries that only have a "Val" entry. This happens when applying a param Sheet using Flex params to compile values using styling logic

func (*Hypers) OpenJSON added in v1.1.50

func (pr *Hypers) OpenJSON(filename gi.FileName) error

OpenJSON opens hypers from a JSON-formatted file.

func (*Hypers) OpenTOML added in v1.4.11

func (pr *Hypers) OpenTOML(filename gi.FileName) error

OpenTOML opens params from a TOML-formatted file.

func (*Hypers) ParamByName added in v1.1.50

func (pr *Hypers) ParamByName(name string) map[string]string

ParamByName returns given parameter by name (just does the map access) Returns "" if not found -- use Try version for error

func (*Hypers) ParamByNameTry added in v1.1.50

func (pr *Hypers) ParamByNameTry(name string) (map[string]string, error)

ParamByNameTry returns given parameter, by name. Returns error if not found.

func (*Hypers) Path added in v1.1.50

func (pr *Hypers) Path(path string) string

Path returns the second part of the path after the target type, indicating the path to the specific parameter being set.

func (*Hypers) SaveGoCode added in v1.1.50

func (pr *Hypers) SaveGoCode(filename gi.FileName) error

SaveGoCode saves hypers to corresponding Go initializer code.

func (*Hypers) SaveJSON added in v1.1.50

func (pr *Hypers) SaveJSON(filename gi.FileName) error

SaveJSON saves hypers to a JSON-formatted file.

func (*Hypers) SaveTOML added in v1.4.11

func (pr *Hypers) SaveTOML(filename gi.FileName) error

SaveTOML saves params to a TOML-formatted file.

func (*Hypers) SetByName added in v1.1.58

func (pr *Hypers) SetByName(name string, value map[string]string)

SetByName sets given parameter by name to given value. (just a wrapper around map set function)

func (*Hypers) StringGoCode added in v1.1.50

func (pr *Hypers) StringGoCode() []byte

StringGoCode returns Go initializer code as a byte string.

func (*Hypers) TargetType added in v1.1.50

func (pr *Hypers) TargetType() string

TargetType returns the first part of the path, indicating what type of object the params apply to. Uses the first item in the map (which is random) everything in the map must have the same target.

func (*Hypers) WriteGoCode added in v1.1.50

func (pr *Hypers) WriteGoCode(w io.Writer, depth int)

WriteGoCode writes hypers to corresponding Go initializer code.

type Params

type Params map[string]string

Params is a name-value map for parameter values that can be applied to any numeric type in any object. The name must be a dot-separated path to a specific parameter, e.g., Prjn.Learn.Lrate The first part of the path is the overall target object type, e.g., "Prjn" or "Layer", which is used for determining if the parameter applies to a given object type.

All of the params in one map must apply to the same target type because only the first item in the map (which could be any due to order randomization) is used for checking the type of the target. Also, they all fall within the same Sel selector scope which is used to determine what specific objects to apply the parameters to.

func (*Params) Apply

func (pr *Params) Apply(obj any, setMsg bool) error

Apply applies all parameter values to given object. Object must already be the appropriate target type based on the first element of the path (see TargetType method). If setMsg is true, then it will log a confirmation that the parameter was set (it always prints an error message if it fails to set the parameter at given path, and returns error if so).

func (*Params) Diffs

func (pr *Params) Diffs(op *Params, nm1, nm2 string) string

Diffs returns comparison between all params in this params versus the other params, where the path is the same but the parameter value is different. Nm1 is the name / id of the 'this' Params, and nm2 is for the other params.

func (*Params) OpenJSON

func (pr *Params) OpenJSON(filename gi.FileName) error

OpenJSON opens params from a JSON-formatted file.

func (*Params) OpenTOML added in v1.4.11

func (pr *Params) OpenTOML(filename gi.FileName) error

OpenTOML opens params from a TOML-formatted file.

func (*Params) ParamByName added in v1.0.0

func (pr *Params) ParamByName(name string) string

ParamByName returns given parameter by name (just does the map access) Returns "" if not found -- use Try version for error

func (*Params) ParamByNameTry added in v1.0.0

func (pr *Params) ParamByNameTry(name string) (string, error)

ParamByNameTry returns given parameter, by name. Returns error if not found.

func (*Params) Path

func (pr *Params) Path(path string) string

Path returns the second part of the path after the target type, indicating the path to the specific parameter being set.

func (*Params) SaveGoCode

func (pr *Params) SaveGoCode(filename gi.FileName) error

SaveGoCode saves params to corresponding Go initializer code.

func (*Params) SaveJSON

func (pr *Params) SaveJSON(filename gi.FileName) error

SaveJSON saves params to a JSON-formatted file.

func (*Params) SaveTOML added in v1.4.11

func (pr *Params) SaveTOML(filename gi.FileName) error

SaveTOML saves params to a TOML-formatted file.

func (*Params) SetByName added in v1.1.58

func (pr *Params) SetByName(name, value string)

SetByName sets given parameter by name to given value. (just a wrapper around map set function)

func (*Params) StringGoCode

func (pr *Params) StringGoCode() []byte

StringGoCode returns Go initializer code as a byte string.

func (*Params) TargetType

func (pr *Params) TargetType() string

TargetType returns the first part of the path, indicating what type of object the params apply to. Uses the first item in the map (which is random) everything in the map must have the same target.

func (*Params) WriteGoCode

func (pr *Params) WriteGoCode(w io.Writer, depth int)

WriteGoCode writes params to corresponding Go initializer code.

type Sel

type Sel struct {

	// selector for what to apply the parameters to, using standard css selector syntax: .Example applies to anything with a Class tag of 'Example', #Example applies to anything with a Name of 'Example', and Example with no prefix applies to anything of type 'Example'
	Sel string `` /* 279-byte string literal not displayed */

	// description of these parameter values -- what effect do they have?  what range was explored?  it is valuable to record this information as you explore the params.
	Desc string `` /* 180-byte string literal not displayed */

	// [view: no-inline] parameter values to apply to whatever matches the selector
	Params Params `view:"no-inline" desc:"parameter values to apply to whatever matches the selector"`

	// Put your hyperparams here
	Hypers Hypers `desc:"Put your hyperparams here"`

	// [tableview: -] number of times this selector matched a target during the last Apply process -- a warning is issued for any that remain at 0 -- see Sheet SelMatchReset and SelNoMatchWarn methods
	NMatch int `` /* 238-byte string literal not displayed */

	// [tableview: -] name of current Set being applied
	SetName string `tableview:"-" toml:"-" json:"-" xml:"-" inactive:"+" desc:"name of current Set being applied"`
}

params.Sel specifies a selector for the scope of application of a set of parameters, using standard css selector syntax (. prefix = class, # prefix = name, and no prefix = type)

func (*Sel) Apply

func (ps *Sel) Apply(obj any, setMsg bool) (bool, error)

Apply checks if Sel selector applies to this object according to (.Class, #Name, Type) using the params.Styler interface, and returns false if it does not. The TargetType of the Params is always tested against the obj's type name first. If it does apply, or is not a Styler, then the Params values are set. If setMsg is true, then a message is printed to confirm each parameter that is set. It always prints a message if a parameter fails to be set, and returns an error.

func (*Sel) OpenJSON

func (pr *Sel) OpenJSON(filename gi.FileName) error

OpenJSON opens params from a JSON-formatted file.

func (*Sel) OpenTOML added in v1.4.11

func (pr *Sel) OpenTOML(filename gi.FileName) error

OpenTOML opens params from a TOML-formatted file.

func (*Sel) ParamVal added in v1.1.57

func (sl *Sel) ParamVal(param string) (string, error)

ParamVal returns the value of given parameter

func (*Sel) SaveGoCode

func (pr *Sel) SaveGoCode(filename gi.FileName) error

SaveGoCode saves params to corresponding Go initializer code.

func (*Sel) SaveJSON

func (pr *Sel) SaveJSON(filename gi.FileName) error

SaveJSON saves params to a JSON-formatted file.

func (*Sel) SaveTOML added in v1.4.11

func (pr *Sel) SaveTOML(filename gi.FileName) error

SaveTOML saves params to a TOML-formatted file.

func (*Sel) SelMatch

func (ps *Sel) SelMatch(obj any) bool

SelMatch returns true if Sel selector matches the target object properties

func (*Sel) SetFloat added in v1.1.58

func (sl *Sel) SetFloat(param string, val float64)

SetFloat sets the value of given parameter

func (*Sel) SetString added in v1.1.58

func (sl *Sel) SetString(param string, val string)

SetString sets the value of given parameter

func (*Sel) StringGoCode

func (pr *Sel) StringGoCode() []byte

StringGoCode returns Go initializer code as a byte string.

func (*Sel) TargetTypeMatch

func (ps *Sel) TargetTypeMatch(obj any) bool

TargetTypeMatch return true if target type applies to object

func (*Sel) WriteGoCode

func (pr *Sel) WriteGoCode(w io.Writer, depth int)

WriteGoCode writes params to corresponding Go initializer code.

type Set

type Set struct {

	// description of this param set -- when should it be used?  how is it different from the other sets?
	Desc string `width:"60" desc:"description of this param set -- when should it be used?  how is it different from the other sets?"`

	// Sheet's grouped according to their target and / or function, e.g.,
	Sheets Sheets `` /* 337-byte string literal not displayed */
}

Set is a collection of Sheets that constitute a coherent set of parameters -- a particular specific configuration of parameters, which the user selects to use. The Set name is stored in the Sets map from which it is typically accessed. A good strategy is to have a "Base" set that has all the best parameters so far, and then other sets can modify relative to that one. It is up to the Sim code to apply parameter sets in whatever order is desired.

Within a params.Set, multiple different params.Sheets can be organized, with each CSS-style sheet achieving a relatively complete parameter styling of a given element of the overal model, e.g., "Network", "Sim", "Env". Or Network could be further broken down into "Learn" vs. "Act" etc, or according to different brain areas ("Hippo", "PFC", "BG", etc). Again, this is entirely at the discretion of the modeler and must be performed under explict program control, especially because order is so critical.

Note that there is NO deterministic ordering of the Sheets due to the use of a Go map structure, which specifically randomizes order, so simply iterating over them and applying may produce unexpected results -- it is better to lookup by name.

func (*Set) Diffs

func (ps *Set) Diffs(ops *Set, name, otherName string) string

Diffs reports all the cases where the same param path is being set to different values between this set and the other set.

func (*Set) DiffsWithin

func (ps *Set) DiffsWithin() string

DiffsWithin reports all the cases where the same param path is being set to different values within different sheets

func (*Set) OpenJSON

func (pr *Set) OpenJSON(filename gi.FileName) error

OpenJSON opens params from a JSON-formatted file.

func (*Set) OpenTOML added in v1.4.11

func (pr *Set) OpenTOML(filename gi.FileName) error

OpenTOML opens params from a TOML-formatted file.

func (*Set) ParamVal added in v1.1.57

func (ps *Set) ParamVal(sheet, sel, param string) (string, error)

ParamVal returns the value of given parameter, in selection sel, in sheet

func (*Set) SaveJSON

func (pr *Set) SaveJSON(filename gi.FileName) error

SaveJSON saves params to a JSON-formatted file.

func (*Set) SaveTOML added in v1.4.11

func (pr *Set) SaveTOML(filename gi.FileName) error

SaveTOML saves params to a TOML-formatted file.

func (*Set) SetFloat added in v1.1.58

func (ps *Set) SetFloat(sheet, sel, param string, val float64) error

SetFloat sets the value of given parameter, in selection sel, in sheet

func (*Set) SetString added in v1.1.58

func (ps *Set) SetString(sheet, sel, param string, val string) error

SetString sets the value of given parameter, in selection sel, in sheet

func (*Set) SheetByName added in v1.0.0

func (ps *Set) SheetByName(name string) *Sheet

SheetByName finds given sheet by name -- returns nil if not found. Use this when sure the sheet exists -- otherwise use Try version.

func (*Set) SheetByNameTry

func (ps *Set) SheetByNameTry(name string) (*Sheet, error)

SheetByNameTry tries to find given sheet by name, and returns error if not found (also logs the error)

func (*Set) ValidateSheets

func (ps *Set) ValidateSheets(valids []string) error

ValidateSheets ensures that the sheet names are among those listed -- returns error message for any that are not. Helps catch typos and makes sure params are applied properly. Automatically logs errors.

func (*Set) WriteGoCode

func (pr *Set) WriteGoCode(w io.Writer, depth int, name string)

WriteGoCode writes params to corresponding Go initializer code.

type Sets

type Sets map[string]*Set

Sets is a collection of Set's that can be chosen among depending on different desired configurations etc. Thus, each Set represents a collection of different possible specific configurations, and different such configurations can be chosen by name to apply as desired.

func (*Sets) DiffsAll

func (ps *Sets) DiffsAll() string

DiffsAll reports all the cases where the same param path is being set to different values across different sets

func (*Sets) DiffsFirst

func (ps *Sets) DiffsFirst() string

DiffsFirst reports all the cases where the same param path is being set to different values between the "Base" set and all other sets. Only works if there is a set named "Base".

func (*Sets) DiffsWithin

func (ps *Sets) DiffsWithin(setName string) string

DiffsWithin reports all the cases where the same param path is being set to different values within different sheets in given set

func (*Sets) OpenJSON

func (pr *Sets) OpenJSON(filename gi.FileName) error

OpenJSON opens params from a JSON-formatted file.

func (*Sets) OpenTOML added in v1.4.11

func (pr *Sets) OpenTOML(filename gi.FileName) error

OpenTOML opens params from a TOML-formatted file.

func (*Sets) ParamVal added in v1.1.57

func (ps *Sets) ParamVal(set, sheet, sel, param string) (string, error)

ParamVal returns the value of given parameter, in selection sel, in sheet and set. Returns error if anything is not found.

func (*Sets) SaveGoCode

func (pr *Sets) SaveGoCode(filename gi.FileName) error

SaveGoCode saves params to corresponding Go initializer code.

func (*Sets) SaveJSON

func (pr *Sets) SaveJSON(filename gi.FileName) error

SaveJSON saves params to a JSON-formatted file.

func (*Sets) SaveTOML added in v1.4.11

func (pr *Sets) SaveTOML(filename gi.FileName) error

SaveTOML saves params to a TOML-formatted file.

func (*Sets) SetByName

func (ps *Sets) SetByName(name string) *Set

SetByName returns given set by name -- for use when confident that it exists, as a nil will return if not found with no error

func (*Sets) SetByNameTry

func (ps *Sets) SetByNameTry(name string) (*Set, error)

SetByNameTry tries to find given set by name, and returns error if not found (also logs the error)

func (*Sets) SetFloat added in v1.1.58

func (ps *Sets) SetFloat(set, sheet, sel, param string, val float64) error

SetFloat sets the value of given parameter, in selection sel, in sheet and set.

func (*Sets) SetString added in v1.1.58

func (ps *Sets) SetString(set, sheet, sel, param string, val string) error

SetString sets the value of given parameter, in selection sel, in sheet and set. Returns error if anything is not found.

func (*Sets) StringGoCode

func (pr *Sets) StringGoCode() []byte

StringGoCode returns Go initializer code as a byte string.

func (*Sets) ValidateSheets

func (ps *Sets) ValidateSheets(valids []string) error

ValidateSheets ensures that the sheet names are among those listed -- returns error message for any that are not. Helps catch typos and makes sure params are applied properly. Automatically logs errors.

func (*Sets) WriteGoCode

func (pr *Sets) WriteGoCode(w io.Writer, depth int)

WriteGoCode writes params to corresponding Go initializer code.

type Sheet

type Sheet []*Sel

Sheet is a CSS-like style-sheet of params.Sel values, each of which represents a different set of specific parameter values applied according to the Sel selector: .Class #Name or Type.

The order of elements in the Sheet list is critical, as they are applied in the order given by the list (slice), and thus later Sel's can override those applied earlier. Thus, you generally want to have more general Type-level parameters listed first, and then subsequently more specific ones (.Class and #Name)

This is the highest level of params that has an Apply method -- above this level application must be done under explicit program control.

func MapToSheet added in v1.4.14

func MapToSheet(vals map[string]any) (*Sheet, error)

MapToSheet returns a Sheet from given map[string]any values, so the Sheet can be applied as such -- e.g., for the network ApplyParams method. The map keys are Selector:Path and the value is the value to apply.

func NewSheet added in v1.4.14

func NewSheet() *Sheet

NewSheet returns a new Sheet

func (*Sheet) Apply

func (ps *Sheet) Apply(obj any, setMsg bool) (bool, error)

Apply applies entire sheet to given object, using param.Sel's in order see param.Sel.Apply() for details. returns true if any Sel's applied, and error if any errors. If setMsg is true, then a message is printed to confirm each parameter that is set. It always prints a message if a parameter fails to be set, and returns an error.

func (*Sheet) Diffs

func (ps *Sheet) Diffs(ops *Sheet, setNm1, setNm2 string) string

Diffs reports all the cases where the same param path is being set to different values between this sheeet and the other sheeet.

func (*Sheet) DiffsWithin

func (ps *Sheet) DiffsWithin(shtNm string) string

DiffsWithin reports all the cases where the same param path is being set to different values within different Sel's in this Sheet.

func (*Sheet) ElemLabel

func (sh *Sheet) ElemLabel(idx int) string

ElemLabel satisfies the gi.SliceLabeler interface to provide labels for slice elements

func (*Sheet) OpenJSON

func (pr *Sheet) OpenJSON(filename gi.FileName) error

OpenJSON opens params from a JSON-formatted file.

func (*Sheet) OpenTOML added in v1.4.11

func (pr *Sheet) OpenTOML(filename gi.FileName) error

OpenTOML opens params from a TOML-formatted file.

func (*Sheet) ParamVal added in v1.1.57

func (sh *Sheet) ParamVal(sel, param string) (string, error)

ParamVal returns the value of given parameter, in selection sel

func (*Sheet) SaveGoCode

func (pr *Sheet) SaveGoCode(filename gi.FileName) error

SaveGoCode saves params to corresponding Go initializer code.

func (*Sheet) SaveJSON

func (pr *Sheet) SaveJSON(filename gi.FileName) error

SaveJSON saves params to a JSON-formatted file.

func (*Sheet) SaveTOML added in v1.4.11

func (pr *Sheet) SaveTOML(filename gi.FileName) error

SaveTOML saves params to a TOML-formatted file.

func (*Sheet) SelByName added in v1.0.0

func (sh *Sheet) SelByName(sel string) *Sel

SelByName returns given selector within the Sheet, by Name. Returns nil if not found -- use Try version for error

func (*Sheet) SelByNameTry added in v1.0.0

func (sh *Sheet) SelByNameTry(sel string) (*Sel, error)

SelByNameTry returns given selector within the Sheet, by Name. Returns nil and error if not found.

func (*Sheet) SelMatchReset added in v1.3.33

func (ps *Sheet) SelMatchReset(setName string)

SelMatchReset resets the Sel.NMatch counter used to find cases where no Sel matched any target objects. Call at start of application process, which may be at an outer-loop of Apply calls (e.g., for a Network, Apply is called for each Layer and Prjn), so this must be called separately. See SelNoMatchWarn for warning call at end.

func (*Sheet) SelNoMatchWarn added in v1.3.33

func (ps *Sheet) SelNoMatchWarn(setName, objName string) error

SelNoMatchWarn issues warning messages for any Sel selectors that had no matches during the last Apply process -- see SelMatchReset. The setName and objName provide info about the Set and obj being applied. Returns an error message with the non-matching sets if any, else nil.

func (*Sheet) SetFloat added in v1.1.58

func (sh *Sheet) SetFloat(sel, param string, val float64) error

SetFloat sets the value of given parameter, in selection sel

func (*Sheet) SetString added in v1.1.58

func (sh *Sheet) SetString(sel, param string, val string) error

SetString sets the value of given parameter, in selection sel

func (*Sheet) StringGoCode

func (pr *Sheet) StringGoCode() []byte

StringGoCode returns Go initializer code as a byte string.

func (*Sheet) WriteGoCode

func (pr *Sheet) WriteGoCode(w io.Writer, depth int)

WriteGoCode writes params to corresponding Go initializer code.

type Sheets

type Sheets map[string]*Sheet

Sheets is a map of named sheets -- used in the Set

func (*Sheets) DiffsWithin

func (ps *Sheets) DiffsWithin() string

DiffsWithin reports all the cases where the same param path is being set to different values within different sheets

func (*Sheets) OpenJSON

func (pr *Sheets) OpenJSON(filename gi.FileName) error

OpenJSON opens params from a JSON-formatted file.

func (*Sheets) OpenTOML added in v1.4.11

func (pr *Sheets) OpenTOML(filename gi.FileName) error

OpenTOML opens params from a TOML-formatted file.

func (*Sheets) SaveGoCode

func (pr *Sheets) SaveGoCode(filename gi.FileName) error

SaveGoCode saves params to corresponding Go initializer code.

func (*Sheets) SaveJSON

func (pr *Sheets) SaveJSON(filename gi.FileName) error

SaveJSON saves params to a JSON-formatted file.

func (*Sheets) SaveTOML added in v1.4.11

func (pr *Sheets) SaveTOML(filename gi.FileName) error

SaveTOML saves params to a TOML-formatted file.

func (*Sheets) StringGoCode

func (pr *Sheets) StringGoCode() []byte

StringGoCode returns Go initializer code as a byte string.

func (*Sheets) WriteGoCode

func (pr *Sheets) WriteGoCode(w io.Writer, depth int)

WriteGoCode writes params to corresponding Go initializer code.

type Styler

type Styler interface {
	// TypeName returns the name of this type. CSS Sel selector with no prefix
	// operates on type name.  This type is used *in addition* to the actual
	// Go type name of the object, and is a kind of type-category (e.g., Layer
	// or Prjn in emergent network objects)
	TypeName() string

	// Class returns the space-separated list of class selectors (tags).
	// Parameters with a . prefix target class tags.
	// Do NOT include the. in the Class tags on Styler objects however
	// -- those are only in the Sel selector on the params.Sel.
	Class() string

	// Name returns the name of this object.
	// Parameters with a # prefix target object names, which are typically
	// unique.  Note, do not include the # prefix in the Styler name.
	Name() string
}

The params.Styler interface exposes TypeName, Class, and Name methods that allow the params.Sel CSS-style selection specifier to determine whether a given parameter applies. Adding Set versions of Name and Class methods is a good idea but not needed for this interface, so they are not included here.

type StylerObj added in v1.1.51

type StylerObj interface {
	Styler

	// Object returns the object that will have its field values set by
	// the params specifications.
	Object() any
}

The params.StylerObj interface extends Styler to include an arbitary function to access the underlying object type.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL