Documentation
¶
Overview ¶
Package psokit is a toolkit for running a collection of, at the moment, experimental Set-based Particle Swarm Optimisers (SPSOs) in the package setpso. These SPSOs are used to find good and often optimal cost minimising subsets where the cost is a function of subsets of a finite collection of items, where the cost is a big integer so that in principle large and combinatorial difficult problems can be looked at. Please read https://github.com/mathrgo/setpso to give background information followed by the godoc documentation.
The main toolkit interface is ManPso; its instance is usually referred to as man which manages the sequence of runs to get some impression of how the chosen SPSO performs with the chosen cost function with Actions that are available for monitoring the runs. All these components (SPSO,Function,Actions) are chosen by name using various Select methods. There are short descriptions against each name and the toolkit provides methods for listing the names and their associated descriptions.
As well as inbuilt components there is an interface to generate new component creators together with their names and brief descriptions which can be moved to the inbuilt components at a later date. In this way a list of ready made components can be built up to deepen the test space for competing algorithms and monitoring methods.
An example of its use is given in the setpso subdirectory
setpso/example/runkit1
This includes the command line option reader Action. When run without arguments command line option help is displayed together with the list of available Actions. to do a single run try
go run runkit1.go -nrun 1
in the runkit1 directory.
Index ¶
- Constants
- func FixLinAxis(a *plot.Axis)
- func FloatingpointDifference(x, y *big.Int) float64
- type Act
- type ActData
- type ActInit
- type ActResult
- type ActRunInit
- type ActSummary
- type ActUpdate
- type CmdOptions
- type CreateFun
- type CreatePso
- type Fun
- type ManPso
- func (man *ManPso) ActDescription() string
- func (man *ManPso) AddAct(name, desc string, a Act) error
- func (man *ManPso) AddFun(name, desc string, f CreateFun) error
- func (man *ManPso) AddPso(name, desc string, p CreatePso) error
- func (man *ManPso) CreateFun(name string) (f Fun)
- func (man *ManPso) CreatePso(name string) (p PsoInterface)
- func (man *ManPso) Datalength() int
- func (man *ManPso) DebugDump() bool
- func (man *ManPso) DelFun(name string) error
- func (man *ManPso) DelPso(name string) error
- func (man *ManPso) Diter() int
- func (man *ManPso) F() Fun
- func (man *ManPso) FunCase() string
- func (man *ManPso) FunDescription() string
- func (man *ManPso) FunSeed() (sd0, sd1 int64)
- func (man *ManPso) Init()
- func (man *ManPso) Iter() int
- func (man *ManPso) Npart() int
- func (man *ManPso) Nrun() int
- func (man *ManPso) Nthink() int
- func (man *ManPso) P() PsoInterface
- func (man *ManPso) PsoCase() string
- func (man *ManPso) PsoDescription() string
- func (man *ManPso) PsoSeed() (sd0, sd1 int64)
- func (man *ManPso) Run()
- func (man *ManPso) RunID() int
- func (man *ManPso) SelectActs(ac ...string) error
- func (man *ManPso) SelectFun(name string) error
- func (man *ManPso) SelectPso(name string) error
- func (man *ManPso) SetDebugDump(db bool)
- func (man *ManPso) SetFunCase(name string)
- func (man *ManPso) SetFunSeed(sd0, sd1 int64)
- func (man *ManPso) SetNpart(n int)
- func (man *ManPso) SetNrun(n int)
- func (man *ManPso) SetNthink(n int)
- func (man *ManPso) SetPsoCase(name string)
- func (man *ManPso) SetPsoSeed(sd0, sd1 int64)
- func (man *ManPso) SetStopAt(n int)
- func (man *ManPso) Setdatalength(n int)
- func (man *ManPso) StopAt() int
- func (man *ManPso) String() string
- type PlotPersonalBest
- type Printheading
- type Printresult
- type PsoInterface
- type ResultsArray
- type RunProgress
Examples ¶
Constants ¶
const DefaultFun = "subsetsum-0"
DefaultFun is the default cost function.
const DefaultPso = "gpso-0"
DefaultPso is the default SPSO.
Variables ¶
This section is empty.
Functions ¶
func FixLinAxis ¶
FixLinAxis attempts to give better min/max bounds for linear axis
func FloatingpointDifference ¶
FloatingpointDifference gives a measure of the difference of the integers x,y as sets and returns the result as a floating point value of the Hamming distance between x and y.
Types ¶
type Act ¶
type Act interface{}
Act is for arbitrary Action, which is placed in the appropriate slots based on its methods.
type ActData ¶
type ActData interface{ DataUpdate(man *ManPso) }
ActData is the interface for data input/output actions that occur at fixed intervals of NThink() iterations. This is used to reduce the communication bandwidth for memory demanding actions such as plotting the progress of the swarm.
type ActInit ¶
type ActInit interface{ Init(man *ManPso) }
ActInit is the interface for pre runs initializing Action. This is expected to be run before the cost-function and SPSO instances are available; it is used to configure man before the run commences; it typically is used to provide a command line interface or even include new things that are not part of the installed options.
type ActResult ¶
type ActResult interface{ Result(man *ManPso) }
ActResult is the interface for post run Action.
type ActRunInit ¶
type ActRunInit interface{ RunInit(man *ManPso) }
ActRunInit is the interface for a run initializing Action. It can change the cost-function and SPSO instances and even swap them if you are not interested in the runs being statistically independent!
type ActSummary ¶
type ActSummary interface{ Summary(man *ManPso) }
ActSummary is the interface for post runs Action.
type ActUpdate ¶
type ActUpdate interface{ Update(man *ManPso) }
ActUpdate is the interface for post Update per iteration Action. This may be used for ultra fine logging of data during a debug dump, update a variance calculation, stop the run before it reaches a maximum number of iterations or even change the nature of the function being optimized.
type CmdOptions ¶
type CmdOptions struct{}
CmdOptions is the implementation of the Action, use-cmd-options. It provides the ability to change some of the man options using the command line. if no CmdOptions are chosen it prints out a list of defaults together with a list of Action names.
type CreatePso ¶
type CreatePso interface {
Create(p0 *setpso.Pso, hu ...*setpso.PsoHeuristics) PsoInterface
}
CreatePso is the interface for creating new instances of SPSO.
type ManPso ¶
type ManPso struct {
// contains filtered or unexported fields
}
ManPso manages the runs.
func NewMan ¶
func NewMan() *ManPso
NewMan creates a default instance of ManPso.
Example ¶
var fc myFun
man := NewMan()
// try adding creator to existing cost-function
if err := man.AddFun("subsetsum-0", "subsetsum of 50 elements", &fc); err != nil {
fmt.Println(err)
}
// try selecting a non existent Fun
if err := man.SelectFun("subsetsum-1"); err != nil {
fmt.Println(err)
}
//try deleting a cost-function that has not been added
if err := man.DelFun("subsetsum-0"); err != nil {
fmt.Println(err)
}
// this should be the default
fmt.Println("\n==default man==")
fmt.Print(man)
// add a new cost function
if err := man.AddFun("subsetsum-1", "subsetsum of 50 elements", &fc); err != nil {
fmt.Println(err)
}
// select it
if err := man.SelectFun("subsetsum-1"); err != nil {
fmt.Println(err)
}
// it is now managed by man
fmt.Println("\n===man with new cost-function==")
fmt.Print(man)
fmt.Print(man.FunDescription())
//delete a function that is added and selected for the runs
if err := man.DelFun("subsetsum-1"); err != nil {
fmt.Println(err)
}
// it is now not managed by man which uses the default
fmt.Println("\n===man with default cost-function==")
fmt.Print(man)
fmt.Print(man.PsoDescription())
/* Output:
*//
Output:
func (*ManPso) ActDescription ¶
ActDescription gives a description of Action by name.
func (*ManPso) AddAct ¶
AddAct adds an Action instance creator to man for it to use later on. the Action has the name name and description desc. If the Action already exists it is not added and an error message is returned.
func (*ManPso) AddFun ¶
AddFun adds a cost function instance f with an assigned name to reference it by where desc is the description of the function. Note one cannot here reuse instance names. It returns true if successful. However, if there is a need to reuse a name that has been added, call DelFun() to remove it.
func (*ManPso) AddPso ¶
AddPso adds a SPSO instance creator p with an assigned name to reference it by where desc is the description of it. Note one cannot here reuse instance names. However, if there is a need to reuse a name that has been added, call DelFun() to remove it.
func (*ManPso) CreateFun ¶
CreateFun returns the cost-function instance based on its name and is called by man at the beginning of each run, so there is no need to call this if using man to execute the run sequence; you can use SelectFun() instead to prime man before a run.
If cost-function not found the the event is logged and it returns nil otherwise it sets up man to use the cost-function.
func (*ManPso) CreatePso ¶
func (man *ManPso) CreatePso(name string) (p PsoInterface)
CreatePso returns the SPSO instance based on its name and is called by man at the beginning of a run, so there is no need to call this if using man to execute the run sequence; you can use SelectPso() instead.
If SPSO is not found the the event is logged and it returns nil otherwise it sets up man to use it . This also assumes the cost-function has been created for man beforehand using CreateFun().
func (*ManPso) Datalength ¶
Datalength is the maximum number of data events per run used mainly for plotting.
func (*ManPso) DelFun ¶
DelFun can be used to delete an added cost function thus freeing resources. it logs the event if not found. As a temporary measure man is set to use the Default cost function if name has been selected.
func (*ManPso) DelPso ¶
DelPso can be used to delete an added SPSO instance creator thus freeing resources.
func (*ManPso) FunDescription ¶
FunDescription gives a description of cost-function by name.
func (*ManPso) FunSeed ¶
FunSeed returns the random generator seed components of the cost-function where seed=sd0+sd1*RunId()
func (*ManPso) Init ¶
func (man *ManPso) Init()
Init sets up man with instance of cost-function and SPSO based on its settings. This is automatically called at the beginning of each run so is normally not explicitly called; it is exportable for those that need it. For instance it is used in some test examples where there is no need to run a case.
func (*ManPso) P ¶
func (man *ManPso) P() PsoInterface
P returns the instance of the SPSO in use for Actions during a run
func (*ManPso) PsoDescription ¶
PsoDescription gives a description of SPSO by name.
func (*ManPso) PsoSeed ¶
PsoSeed returns the random generator seed components of SPSO where seed=sd0+sd1*RunId().
func (*ManPso) Run ¶
func (man *ManPso) Run()
Run runs the chosen SPSO using the chosen cost-function and settings in man for Nrun() runs. Each run starts with a new cost-function and SPSO with different but computed random number seeds to aim at making each run independent of other runs in the sequence thus making it easy to generate moderately unbiased performance statistics.
During the runs chosen Actions are activated according to their interfaces.
func (*ManPso) SelectActs ¶
SelectActs selects a list of actions by name to be added for used by man. Each Action is slotted into the runs where they have a capability to act.
Example ¶
man := NewMan()
if err := man.SelectActs("print-result"); err != nil {
fmt.Println(err)
}
// ensure there are instances to apply print-result
man.Init()
// go under the hood to see if SelectActs() has installed the action
r := man.actResult[0]
r.Result(man)
/* Output:
*//
Output:
func (*ManPso) SelectFun ¶
SelectFun informs man to consider using the named cost-function instance, name. it checks that there exists an instance creator and returns an error if it does not exist. There is no need to add a cost-function if you are using an inbuilt instance name.
func (*ManPso) SelectPso ¶
SelectPso primes man to consider using the named SPSO instance creator, name, for the runs. It checks that there exists an instance creator and returns an error if it does not exist.There is no need to add a PSO using AddPso if you are using an inbuilt instance creator name.
func (*ManPso) SetDebugDump ¶
SetDebugDump sets DebugDump flag.
func (*ManPso) SetFunCase ¶
SetFunCase sets the cost-function case name.
func (*ManPso) SetFunSeed ¶
SetFunSeed sets the cost_function seed components.
func (*ManPso) SetPsoCase ¶
SetPsoCase sets the SPSo case name.
func (*ManPso) SetPsoSeed ¶
SetPsoSeed sets the SPSO seed components.
func (*ManPso) Setdatalength ¶
Setdatalength sets datalength.
type PlotPersonalBest ¶
type PlotPersonalBest struct {
*ResultsArray
}
PlotPersonalBest plots the personal best costs of each Particle during a run. It implements the plot-personal-best Action.
func (*PlotPersonalBest) DataUpdate ¶
func (pl *PlotPersonalBest) DataUpdate(man *ManPso)
DataUpdate loads personal best costs into plot
func (*PlotPersonalBest) Result ¶
func (pl *PlotPersonalBest) Result(man *ManPso)
Result generates the plots of the personal best and puts it into the file of the form:
plotFbits(Cost)<run ID>.pdf
func (*PlotPersonalBest) RunInit ¶
func (pl *PlotPersonalBest) RunInit(man *ManPso)
RunInit setup plotting arrays for the run
type Printheading ¶
type Printheading struct{}
Printheading used as the Action, print-headings
func (*Printheading) RunInit ¶
func (a *Printheading) RunInit(man *ManPso)
RunInit outputs information about the cost-function. If the seed does not vary between runs it only outputs on the first run
type Printresult ¶
type Printresult struct{}
Printresult used as the Action, print-result
func (*Printresult) Result ¶
func (a *Printresult) Result(man *ManPso)
Result just prints the run result as cost and decoded subset
type PsoInterface ¶
type PsoInterface = setpso.PsoInterface
PsoInterface is the PsoInterface from setpso.
type ResultsArray ¶
type ResultsArray struct {
// contains filtered or unexported fields
}
ResultsArray is a structure for storing and plotting results from Each particle
func NewResultsArray ¶
func NewResultsArray(datalength, dimension int) *ResultsArray
NewResultsArray creates a Results Array and returns a pointer to it. It consists of datalength data entries for dimension values per entry.
func (*ResultsArray) NewPlot ¶
func (r *ResultsArray) NewPlot(yaxisname, title string, runid int)
NewPlot creates a basic plot. yaxisname is the Y-axis label; title is the plot title; runid is the run ID.
func (*ResultsArray) ResUpdate ¶
func (r *ResultsArray) ResUpdate(val float64, dataID, valID, iterID int)
ResUpdate puts val into the plotting results array for value index valueID and data slot dataID where valID is the number of iterations so far in a run.
type RunProgress ¶
type RunProgress struct {
// contains filtered or unexported fields
}
RunProgress output progress statements during the run
func (*RunProgress) DataUpdate ¶
func (a *RunProgress) DataUpdate(man *ManPso)
DataUpdate checks progress and prints out a change in progress
func (*RunProgress) RunInit ¶
func (a *RunProgress) RunInit(man *ManPso)
RunInit initializes the progres counter
Source Files