goptuna

package module
v0.0.3 Latest Latest
Warning

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

 Go to latest Published: Aug 5, 2019 License: MIT Imports: 10 Imported by: 44

README

Goptuna

Software License GoDoc Go Report Card

Bayesian optimization framework for black-box functions, inspired by Optuna. This library is not only for hyperparameter tuning of machine learning models. Everything will be able to optimize if you can define the objective function (e.g. Optimizing the number of goroutines of your server and the memory buffer size of the caching systems).

Currently two algorithms are implemented:

  • Random Search
  • Tree-structured Parzen Estimators (TPE)
  • Median Stopping Rule (Google Vizier)

See the blog post for more details: Practical bayesian optimization in Go using Goptuna.

Installation

You can integrate Goptuna in wide variety of Go projects because of its portability of pure Go.

$ go get -u github.com/c-bata/goptuna

Usage

Goptuna supports Define-By-Run style user API like Optuna. It makes the modularity high, and the user can dynamically construct the search spaces.

package main

import (
    "fmt"
    "math"

    "github.com/c-bata/goptuna"
    "github.com/c-bata/goptuna/tpe"
    "go.uber.org/zap"
)

func objective(trial goptuna.Trial) (float64, error) {
    x1, _ := trial.SuggestUniform("x1", -10, 10)
    x2, _ := trial.SuggestUniform("x2", -10, 10)
    return math.Pow(x1-2, 2) + math.Pow(x2+5, 2), nil
}

func main() {
    logger, _ := zap.NewDevelopment()
    defer logger.Sync()

    study, _ := goptuna.CreateStudy(
        "goptuna-example",
        goptuna.StudyOptionSampler(tpe.NewSampler()),
        goptuna.StudyOptionSetDirection(goptuna.StudyDirectionMinimize),
        goptuna.StudyOptionSetLogger(logger),
    )
    _ = study.Optimize(objective, 100)

    v, _ := study.GetBestValue()
    params, _ := study.GetBestParams()
    fmt.Println("result:", v, params)
}

Advanced usages

Parallel optimization with multiple goroutine workers

Optimize method of goptuna.Study object is designed as the goroutine safe. So you can easily optimize your objective function using multiple goroutine workers.

package main

import ...

func main() {
    study, _ := goptuna.CreateStudy(...)

    eg, ctx := errgroup.WithContext(context.Background())
    study.WithContext(ctx)
    for i := 0; i < 5; i++ {
        eg.Go(func() error {
            return study.Optimize(objective, 100)
        })
    }
    if err := eg.Wait(); err != nil { ... }
    ...
}

full source code

Receive notifications of each trials

You can receive notifications of each trials via channel. It can be used for logging and any notification systems.

package main

import ...

func main() {
    trialchan := make(chan goptuna.FrozenTrial, 8)
    study, _ := goptuna.CreateStudy(
        ...
        goptuna.StudyOptionIgnoreObjectiveErr(true),
        goptuna.StudyOptionSetTrialNotifyChannel(trialchan),
    )

    var wg sync.WaitGroup
    wg.Add(2)
    go func() {
        defer wg.Done()
        err = study.Optimize(objective, 100)
        close(trialchan)
    }()
    go func() {
        defer wg.Done()
        for t := range trialchan {
            log.Println("trial", t)
        }
    }()
    wg.Wait()
    if err != nil { ... }
    ...
}

full source code

References:

Status:

License

This software is licensed under the MIT license, see LICENSE for more information.

Documentation

Index

Examples

Constants

View Source 
const CategoricalDistributionName = "CategoricalDistribution"

CategoricalDistributionName is the identifier name of CategoricalDistribution

View Source 
const DiscreteUniformDistributionName = "DiscreteUniformDistribution"

DiscreteUniformDistributionName is the identifier name of DiscreteUniformDistribution

View Source 
const InMemoryStorageStudyID = 1

InMemoryStorageStudyID is a study id for in memory storage backend.

View Source 
const InMemoryStorageStudyUUID = "00000000-0000-0000-0000-000000000000"

InMemoryStorageStudyUUID is a UUID for in memory storage backend

View Source 
const IntUniformDistributionName = "IntUniformDistribution"

IntUniformDistributionName is the identifier name of IntUniformDistribution

View Source 
const LogUniformDistributionName = "LogUniformDistribution"

LogUniformDistributionName is the identifier name of LogUniformDistribution

View Source 
const UniformDistributionName = "UniformDistribution"

UniformDistributionName is the identifier name of UniformDistribution

Variables

View Source 
var (
	// ErrNotFound represents not found.
	ErrNotFound = errors.New("not found")
	// ErrInvalidStudyID represents invalid study id.
	ErrInvalidStudyID = errors.New("invalid study id")
	// ErrInvalidTrialID represents invalid trial id.
	ErrInvalidTrialID = errors.New("invalid trial id")
	// ErrTrialCannotBeUpdated represents trial cannot be updated.
	ErrTrialCannotBeUpdated = errors.New("trial cannot be updated")
	// ErrNoCompletedTrials represents no trials are completed yet.
	ErrNoCompletedTrials = errors.New("no trials are completed yet")
	// ErrUnknownDistribution returns the distribution is unknown.
	ErrUnknownDistribution = errors.New("unknown distribution")
	// ErrTrialPruned represents the pruned.
	ErrTrialPruned = errors.New("trial is pruned")
)
View Source 
var DefaultStudyNamePrefix = "no-name-"

DefaultStudyNamePrefix is a prefix of the default study name.

Functions

func DistributionToJSON added in v0.0.2 

func DistributionToJSON(distribution interface{}) ([]byte, error)

DistributionToJSON serialize a distribution to JSON format.

func JSONToDistribution added in v0.0.2 

func JSONToDistribution(jsonBytes []byte) (interface{}, error)

JSONToDistribution deserialize a distribution in JSON format.

Types

type CategoricalDistribution added in v0.0.2 

type CategoricalDistribution struct {
	// Choices is a candidates of parameter values
	Choices []string `json:"choices"`
}

CategoricalDistribution is a distribution for categorical parameters

func (*CategoricalDistribution) Contains added in v0.0.2 

func (d *CategoricalDistribution) Contains(ir float64) bool

Contains to check a parameter value is contained in the range of this distribution.

func (*CategoricalDistribution) Single added in v0.0.2 

func (d *CategoricalDistribution) Single() bool

Single to test whether the range of this distribution contains just a single value.

func (*CategoricalDistribution) ToExternalRepr added in v0.0.2 

func (d *CategoricalDistribution) ToExternalRepr(ir float64) interface{}

ToExternalRepr to convert internal representation of a parameter value into external representation.

func (*CategoricalDistribution) ToInternalRepr added in v0.0.2 

func (d *CategoricalDistribution) ToInternalRepr(er interface{}) float64

ToInternalRepr to convert external representation of a parameter value into internal representation.

type DiscreteUniformDistribution added in v0.0.3 

type DiscreteUniformDistribution struct {
	// High is higher endpoint of the range of the distribution (included in the range).
	High float64 `json:"high"`
	// Low is lower endpoint of the range of the distribution (included in the range).
	Low float64 `json:"low"`
	// Q is a discretization step.
	Q float64 `json:"q"`
}

DiscreteUniformDistribution is a discretized uniform distribution in the linear domain.

func (*DiscreteUniformDistribution) Contains added in v0.0.3 

func (d *DiscreteUniformDistribution) Contains(ir float64) bool

Contains to check a parameter value is contained in the range of this distribution.

func (*DiscreteUniformDistribution) Single added in v0.0.3 

func (d *DiscreteUniformDistribution) Single() bool

Single to test whether the range of this distribution contains just a single value.

func (*DiscreteUniformDistribution) ToExternalRepr added in v0.0.3 

func (d *DiscreteUniformDistribution) ToExternalRepr(ir float64) interface{}

ToExternalRepr to convert internal representation of a parameter value into external representation.

func (*DiscreteUniformDistribution) ToInternalRepr added in v0.0.3 

func (d *DiscreteUniformDistribution) ToInternalRepr(xr interface{}) float64

ToInternalRepr to convert external representation of a parameter value into internal representation.

type Distribution 

type Distribution interface {
	// ToInternalRepr to convert external representation of a parameter value into internal representation.
	ToInternalRepr(interface{}) float64
	// ToExternalRepr to convert internal representation of a parameter value into external representation.
	ToExternalRepr(float64) interface{}
	// Single to test whether the range of this distribution contains just a single value.
	Single() bool
	// Contains to check a parameter value is contained in the range of this distribution.
	Contains(float64) bool
}

Distribution represents a parameter that can be optimized.

type FrozenTrial 

type FrozenTrial struct {
	ID                 int                     `json:"trial_id"`
	StudyID            int                     `json:"study_id"`
	Number             int                     `json:"number"`
	State              TrialState              `json:"state"`
	Value              float64                 `json:"value"`
	IntermediateValues map[int]float64         `json:"intermediate_values"`
	DatetimeStart      time.Time               `json:"datetime_start"`
	DatetimeComplete   time.Time               `json:"datetime_complete"`
	Params             map[string]interface{}  `json:"params"`
	Distributions      map[string]Distribution `json:"distributions"`
	UserAttrs          map[string]interface{}  `json:"user_attrs"`
	SystemAttrs        map[string]interface{}  `json:"system_attrs"`
	// Note: ParamsInIR is private in Optuna.
	// But we need to keep public because this is accessed by TPE sampler.
	// It couldn't access internal attributes from the external packages.
	// https://github.com/pfnet/optuna/pull/462
	ParamsInIR map[string]float64 `json:"params_in_internal_repr"`
}

FrozenTrial holds the status and results of a Trial.

type FuncObjective 

type FuncObjective func(trial Trial) (float64, error)

FuncObjective is a type of objective function

type InMemoryStorage 

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

InMemoryStorage stores data in memory of the Go process.

func NewInMemoryStorage 

func NewInMemoryStorage() *InMemoryStorage

NewInMemoryStorage returns new memory storage.

func (*InMemoryStorage) CreateNewStudyID 

func (s *InMemoryStorage) CreateNewStudyID(name string) (int, error)

CreateNewStudyID creates study and returns studyID.

Example 
package main

import (
	"fmt"

	"github.com/c-bata/goptuna"
)

func main() {
	storage := goptuna.NewInMemoryStorage()
	studyID, err := storage.CreateNewStudyID("")
	if err != nil {
		panic(err)
	}
	fmt.Println(studyID)

}

Output:

1

func (*InMemoryStorage) CreateNewTrialID 

func (s *InMemoryStorage) CreateNewTrialID(studyID int) (int, error)

CreateNewTrialID creates trial and returns trialID.

func (*InMemoryStorage) GetAllStudySummaries added in v0.0.2 

func (s *InMemoryStorage) GetAllStudySummaries(studyID int) ([]StudySummary, error)

GetAllStudySummaries returns all study summaries.

func (*InMemoryStorage) GetAllTrials 

func (s *InMemoryStorage) GetAllTrials(studyID int) ([]FrozenTrial, error)

GetAllTrials returns the all trials.

func (*InMemoryStorage) GetBestTrial 

func (s *InMemoryStorage) GetBestTrial(studyID int) (FrozenTrial, error)

GetBestTrial returns the best trial.

func (*InMemoryStorage) GetStudyDirection 

func (s *InMemoryStorage) GetStudyDirection(studyID int) (StudyDirection, error)

GetStudyDirection returns study direction of the objective.

func (*InMemoryStorage) GetStudyIDFromName added in v0.0.2 

func (s *InMemoryStorage) GetStudyIDFromName(name string) (int, error)

GetStudyIDFromName return the study id from study name.

func (*InMemoryStorage) GetStudyIDFromTrialID added in v0.0.2 

func (s *InMemoryStorage) GetStudyIDFromTrialID(trialID int) (int, error)

GetStudyIDFromTrialID return the study id from trial id.

Example 
package main

import (
	"fmt"

	"github.com/c-bata/goptuna"
)

func main() {
	storage := goptuna.NewInMemoryStorage()
	studyID, err := storage.CreateNewStudyID("")
	if err != nil {
		panic(err)
	}
	trialID, err := storage.CreateNewTrialID(studyID)
	if err != nil {
		panic(err)
	}

	actual, err := storage.GetStudyIDFromTrialID(trialID)
	if err != nil {
		panic(err)
	}
	fmt.Println(actual)
}

Output:

1

func (*InMemoryStorage) GetStudyNameFromID added in v0.0.2 

func (s *InMemoryStorage) GetStudyNameFromID(studyID int) (string, error)

GetStudyNameFromID return the study name from study id.

func (*InMemoryStorage) GetStudySystemAttrs added in v0.0.2 

func (s *InMemoryStorage) GetStudySystemAttrs(studyID int) (map[string]interface{}, error)

GetStudySystemAttrs to restore the attributes for the system.

func (*InMemoryStorage) GetStudyUserAttrs added in v0.0.2 

func (s *InMemoryStorage) GetStudyUserAttrs(studyID int) (map[string]interface{}, error)

GetStudyUserAttrs to restore the attributes for the user.

func (*InMemoryStorage) GetTrial 

func (s *InMemoryStorage) GetTrial(trialID int) (FrozenTrial, error)

GetTrial returns Trial.

func (*InMemoryStorage) GetTrialNumberFromID added in v0.0.2 

func (s *InMemoryStorage) GetTrialNumberFromID(trialID int) (int, error)

GetTrialNumberFromID returns the trial's number.

func (*InMemoryStorage) GetTrialParam added in v0.0.2 

func (s *InMemoryStorage) GetTrialParam(trialID int, paramName string) (float64, error)

GetTrialParam returns the internal parameter of the trial

func (*InMemoryStorage) GetTrialParams added in v0.0.2 

func (s *InMemoryStorage) GetTrialParams(trialID int) (map[string]interface{}, error)

GetTrialParams returns the external parameters in the trial

func (*InMemoryStorage) GetTrialSystemAttrs added in v0.0.2 

func (s *InMemoryStorage) GetTrialSystemAttrs(trialID int) (map[string]interface{}, error)

GetTrialSystemAttrs to restore the attributes for the system.

func (*InMemoryStorage) GetTrialUserAttrs added in v0.0.2 

func (s *InMemoryStorage) GetTrialUserAttrs(trialID int) (map[string]interface{}, error)

GetTrialUserAttrs to restore the attributes for the user.

func (*InMemoryStorage) SetStudyDirection 

func (s *InMemoryStorage) SetStudyDirection(studyID int, direction StudyDirection) error

SetStudyDirection sets study direction of the objective.

func (*InMemoryStorage) SetStudySystemAttr added in v0.0.2 

func (s *InMemoryStorage) SetStudySystemAttr(studyID int, key string, value interface{}) error

SetStudySystemAttr to store the value for the system.

Example 
package main

import (
	"fmt"

	"github.com/c-bata/goptuna"
)

func main() {
	storage := goptuna.NewInMemoryStorage()
	studyID, err := storage.CreateNewStudyID("")
	if err != nil {
		panic(err)
	}
	err = storage.SetStudySystemAttr(studyID, "key", "value")
	if err != nil {
		panic(err)
	}
	attrs, err := storage.GetStudySystemAttrs(studyID)
	if err != nil {
		panic(err)
	}
	for k, v := range attrs {
		fmt.Println(k, v)
	}
}

Output:

key value

func (*InMemoryStorage) SetStudyUserAttr added in v0.0.2 

func (s *InMemoryStorage) SetStudyUserAttr(studyID int, key string, value interface{}) error

SetStudyUserAttr to store the value for the user.

Example 
package main

import (
	"fmt"

	"github.com/c-bata/goptuna"
)

func main() {
	storage := goptuna.NewInMemoryStorage()
	studyID, err := storage.CreateNewStudyID("")
	if err != nil {
		panic(err)
	}
	err = storage.SetStudyUserAttr(studyID, "key", "value")
	if err != nil {
		panic(err)
	}
	attrs, err := storage.GetStudyUserAttrs(studyID)
	if err != nil {
		panic(err)
	}
	for k, v := range attrs {
		fmt.Println(k, v)
	}

}

Output:

key value

func (*InMemoryStorage) SetTrialIntermediateValue added in v0.0.3 

func (s *InMemoryStorage) SetTrialIntermediateValue(trialID int, step int, value float64) error

SetTrialIntermediateValue sets the intermediate value of trial.

func (*InMemoryStorage) SetTrialParam 

func (s *InMemoryStorage) SetTrialParam(
	trialID int,
	paramName string,
	paramValueInternal float64,
	distribution Distribution) error

SetTrialParam sets the sampled parameters of trial.

func (*InMemoryStorage) SetTrialState 

func (s *InMemoryStorage) SetTrialState(trialID int, state TrialState) error

SetTrialState sets the state of trial.

func (*InMemoryStorage) SetTrialSystemAttr added in v0.0.2 

func (s *InMemoryStorage) SetTrialSystemAttr(trialID int, key string, value interface{}) error

SetTrialSystemAttr to store the value for the system.

Example 
package main

import (
	"fmt"

	"github.com/c-bata/goptuna"
)

func main() {
	storage := goptuna.NewInMemoryStorage()
	studyID, err := storage.CreateNewStudyID("")
	if err != nil {
		panic(err)
	}
	trialID, err := storage.CreateNewTrialID(studyID)
	if err != nil {
		panic(err)
	}

	err = storage.SetTrialSystemAttr(trialID, "key", "value")
	if err != nil {
		panic(err)
	}
	attrs, err := storage.GetTrialSystemAttrs(trialID)
	if err != nil {
		panic(err)
	}
	for k, v := range attrs {
		fmt.Println(k, v)
	}
}

Output:

key value

func (*InMemoryStorage) SetTrialUserAttr added in v0.0.2 

func (s *InMemoryStorage) SetTrialUserAttr(trialID int, key string, value interface{}) error

SetTrialUserAttr to store the value for the user.

Example 
package main

import (
	"fmt"

	"github.com/c-bata/goptuna"
)

func main() {
	storage := goptuna.NewInMemoryStorage()
	studyID, err := storage.CreateNewStudyID("")
	if err != nil {
		panic(err)
	}
	trialID, err := storage.CreateNewTrialID(studyID)
	if err != nil {
		panic(err)
	}

	err = storage.SetTrialUserAttr(trialID, "key", "value")
	if err != nil {
		panic(err)
	}
	attrs, err := storage.GetTrialUserAttrs(trialID)
	if err != nil {
		panic(err)
	}
	for k, v := range attrs {
		fmt.Println(k, v)
	}

}

Output:

key value

func (*InMemoryStorage) SetTrialValue 

func (s *InMemoryStorage) SetTrialValue(trialID int, value float64) error

SetTrialValue sets the value of trial.

type IntUniformDistribution 

type IntUniformDistribution struct {
	// High is higher endpoint of the range of the distribution (included in the range).
	High int `json:"high"`
	// Low is lower endpoint of the range of the distribution (included in the range).
	Low int `json:"low"`
}

IntUniformDistribution is a uniform distribution on integers.

func (*IntUniformDistribution) Contains added in v0.0.2 

func (d *IntUniformDistribution) Contains(ir float64) bool

Contains to check a parameter value is contained in the range of this distribution.

func (*IntUniformDistribution) Single added in v0.0.2 

func (d *IntUniformDistribution) Single() bool

Single to test whether the range of this distribution contains just a single value.

func (*IntUniformDistribution) ToExternalRepr added in v0.0.2 

func (d *IntUniformDistribution) ToExternalRepr(ir float64) interface{}

ToExternalRepr to convert internal representation of a parameter value into external representation.

func (*IntUniformDistribution) ToInternalRepr added in v0.0.2 

func (d *IntUniformDistribution) ToInternalRepr(xr interface{}) float64

ToInternalRepr to convert external representation of a parameter value into internal representation.

type LogUniformDistribution added in v0.0.3 

type LogUniformDistribution struct {
	// High is higher endpoint of the range of the distribution (included in the range).
	High float64 `json:"high"`
	// Low is lower endpoint of the range of the distribution (included in the range).
	Low float64 `json:"low"`
}

LogUniformDistribution is a uniform distribution in the log domain.

func (*LogUniformDistribution) Contains added in v0.0.3 

func (d *LogUniformDistribution) Contains(ir float64) bool

Contains to check a parameter value is contained in the range of this distribution.

func (*LogUniformDistribution) Single added in v0.0.3 

func (d *LogUniformDistribution) Single() bool

Single to test whether the range of this distribution contains just a single value.

func (*LogUniformDistribution) ToExternalRepr added in v0.0.3 

func (d *LogUniformDistribution) ToExternalRepr(ir float64) interface{}

ToExternalRepr to convert internal representation of a parameter value into external representation.

func (*LogUniformDistribution) ToInternalRepr added in v0.0.3 

func (d *LogUniformDistribution) ToInternalRepr(xr interface{}) float64

ToInternalRepr to convert external representation of a parameter value into internal representation.

type Pruner added in v0.0.3 

type Pruner interface {
	// Prune judge whether the trial should be pruned at the given step.
	Prune(storage Storage, studyID, trialID int, step int) (bool, error)
}

Pruner is a interface for early stopping algorithms.

type RandomSearchSampler 

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

RandomSearchSampler for random search

func NewRandomSearchSampler 

func NewRandomSearchSampler(opts ...RandomSearchSamplerOption) *RandomSearchSampler

NewRandomSearchSampler implements random search algorithm.

func (*RandomSearchSampler) Sample 

func (s *RandomSearchSampler) Sample(
	study *Study,
	trial FrozenTrial,
	paramName string,
	paramDistribution interface{},
) (float64, error)

Sample a parameter for a given distribution.

type RandomSearchSamplerOption 

type RandomSearchSamplerOption func(sampler *RandomSearchSampler)

RandomSearchSamplerOption is a type of function to set change the option.

func RandomSearchSamplerOptionSeed 

func RandomSearchSamplerOptionSeed(seed int64) RandomSearchSamplerOption

RandomSearchSamplerOptionSeed sets seed number.

type Sampler 

type Sampler interface {
	// Sample a parameter for a given distribution.
	Sample(*Study, FrozenTrial, string, interface{}) (float64, error)
}

Sampler returns the next search points

type Storage 

type Storage interface {
	// Basic study manipulation
	CreateNewStudyID(name string) (int, error)
	SetStudyDirection(studyID int, direction StudyDirection) error
	SetStudyUserAttr(studyID int, key string, value interface{}) error
	SetStudySystemAttr(studyID int, key string, value interface{}) error
	// Basic study access
	GetStudyIDFromName(name string) (int, error)
	GetStudyIDFromTrialID(trialID int) (int, error)
	GetStudyNameFromID(studyID int) (string, error)
	GetStudyDirection(studyID int) (StudyDirection, error)
	GetStudyUserAttrs(studyID int) (map[string]interface{}, error)
	GetStudySystemAttrs(studyID int) (map[string]interface{}, error)
	GetAllStudySummaries(studyID int) ([]StudySummary, error)
	// Basic trial manipulation
	CreateNewTrialID(studyID int) (int, error)
	SetTrialValue(trialID int, value float64) error
	SetTrialIntermediateValue(trialID int, step int, value float64) error
	SetTrialParam(trialID int, paramName string, paramValueInternal float64,
		distribution Distribution) error
	SetTrialState(trialID int, state TrialState) error
	SetTrialUserAttr(trialID int, key string, value interface{}) error
	SetTrialSystemAttr(trialID int, key string, value interface{}) error
	// Basic trial access
	GetTrialNumberFromID(trialID int) (int, error)
	GetTrialParam(trialID int, paramName string) (float64, error)
	GetTrial(trialID int) (FrozenTrial, error)
	GetAllTrials(studyID int) ([]FrozenTrial, error)
	GetBestTrial(studyID int) (FrozenTrial, error)
	GetTrialParams(trialID int) (map[string]interface{}, error)
	GetTrialUserAttrs(trialID int) (map[string]interface{}, error)
	GetTrialSystemAttrs(trialID int) (map[string]interface{}, error)
}

Storage interface abstract a backend database and provide library internal interfaces to read/write history of studies and trials. This interface is not supposed to be directly accessed by library users.

type Study 

type Study struct {
	ID      int
	Storage Storage
	Sampler Sampler
	Pruner  Pruner
	// contains filtered or unexported fields
}

Study corresponds to an optimization task, i.e., a set of trials.

func CreateStudy 

func CreateStudy(
	name string,
	opts ...StudyOption,
) (*Study, error)

CreateStudy creates a new Study object.

func (*Study) Direction 

func (s *Study) Direction() StudyDirection

Direction returns the direction of objective function value

func (*Study) GetBestParams 

func (s *Study) GetBestParams() (map[string]interface{}, error)

GetBestParams return parameters of the best trial

func (*Study) GetBestValue 

func (s *Study) GetBestValue() (float64, error)

GetBestValue return the best objective value

func (*Study) GetTrials 

func (s *Study) GetTrials() ([]FrozenTrial, error)

GetTrials returns all trials in this study.

func (*Study) Optimize 

func (s *Study) Optimize(objective FuncObjective, evaluateMax int) error

Optimize optimizes an objective function.

Example 
package main

import (
	"fmt"
	"math"

	"github.com/c-bata/goptuna"
)

func main() {
	sampler := goptuna.NewRandomSearchSampler(
		goptuna.RandomSearchSamplerOptionSeed(0),
	)
	study, _ := goptuna.CreateStudy(
		"example",
		goptuna.StudyOptionSetDirection(goptuna.StudyDirectionMinimize),
		goptuna.StudyOptionSampler(sampler),
	)

	objective := func(trial goptuna.Trial) (float64, error) {
		x1, _ := trial.SuggestUniform("x1", -10, 10)
		x2, _ := trial.SuggestUniform("x2", -10, 10)
		return math.Pow(x1-2, 2) + math.Pow(x2+5, 2), nil
	}

	if err := study.Optimize(objective, 10); err != nil {
		panic(err)
	}
	value, _ := study.GetBestValue()
	params, _ := study.GetBestParams()

	fmt.Printf("Best trial: %.5f\n", value)
	fmt.Printf("x1: %.3f\n", params["x1"])
	fmt.Printf("x2: %.3f\n", params["x2"])
}

Output:

Best trial: 0.03833
x1: 2.182
x2: -4.927

func (*Study) Report 

func (s *Study) Report(trialID int, value float64) error

Report reports an objective function value

func (*Study) WithContext added in v0.0.2 

func (s *Study) WithContext(ctx context.Context)

WithContext sets a context and it might cancel the execution of Optimize.

type StudyDirection 

type StudyDirection string

StudyDirection represents the direction of the optimization 

const (
	// StudyDirectionMaximize maximizes objective function value
	StudyDirectionMaximize StudyDirection = "maximize"
	// StudyDirectionMinimize minimizes objective function value
	StudyDirectionMinimize StudyDirection = "minimize"
)

type StudyOption 

type StudyOption func(study *Study) error

StudyOption to pass the custom option

func StudyOptionIgnoreObjectiveErr 

func StudyOptionIgnoreObjectiveErr(ignore bool) StudyOption

StudyOptionIgnoreObjectiveErr sets the option to ignore error returned from objective function If true, Optimize method continues to run new trial.

func StudyOptionPruner added in v0.0.3 

func StudyOptionPruner(pruner Pruner) StudyOption

StudyOptionPruner sets the pruner object.

func StudyOptionSampler 

func StudyOptionSampler(sampler Sampler) StudyOption

StudyOptionSampler sets the sampler object.

func StudyOptionSetDirection 

func StudyOptionSetDirection(direction StudyDirection) StudyOption

StudyOptionSetDirection change the direction of optimize

func StudyOptionSetLogger 

func StudyOptionSetLogger(logger *zap.Logger) StudyOption

StudyOptionSetLogger sets zap.Logger.

func StudyOptionSetTrialNotifyChannel 

func StudyOptionSetTrialNotifyChannel(notify chan FrozenTrial) StudyOption

StudyOptionSetTrialNotifyChannel to subscribe the finished trials.

func StudyOptionStorage 

func StudyOptionStorage(storage Storage) StudyOption

StudyOptionStorage sets the storage object.

type StudySummary added in v0.0.2 

type StudySummary struct {
	ID            int                    `json:"study_id"`
	Name          string                 `json:"study_name"`
	Direction     StudyDirection         `json:"direction"`
	BestTrial     FrozenTrial            `json:"best_trial"`
	UserAttrs     map[string]interface{} `json:"user_attrs"`
	SystemAttrs   map[string]interface{} `json:"system_attrs"`
	DatetimeStart time.Time              `json:"datetime_start"`
}

StudySummary holds basic attributes and aggregated results of Study.

type Trial 

type Trial struct {
	Study *Study
	ID    int
	// contains filtered or unexported fields
}

Trial is a process of evaluating an objective function.

This object is passed to an objective function and provides interfaces to get parameter suggestion, manage the trial's state of the trial. Note that this object is seamlessly instantiated and passed to the objective function behind; hence, in typical use cases, library users do not care about instantiation of this object.

func (*Trial) Number added in v0.0.3 

func (t *Trial) Number() (int, error)

Number return trial's number which is consecutive and unique in a study.

func (*Trial) Report added in v0.0.3 

func (t *Trial) Report(value float64, step int) error

Report an intermediate value of an objective function

func (*Trial) ShouldPrune added in v0.0.3 

func (t *Trial) ShouldPrune(value float64) (bool, error)

ShouldPrune judges whether the trial should be pruned. This method calls prune method of the pruner, which judges whether the trial should be pruned at the given step.

func (*Trial) SuggestCategorical added in v0.0.2 

func (t *Trial) SuggestCategorical(name string, choices []string) (string, error)

SuggestCategorical suggests an categorical parameter.

func (*Trial) SuggestInt 

func (t *Trial) SuggestInt(name string, low, high int) (int, error)

SuggestInt suggests an integer parameter.

Example 
package main

import (
	"fmt"
	"math"

	"github.com/c-bata/goptuna"
)

func main() {
	sampler := goptuna.NewRandomSearchSampler(
		goptuna.RandomSearchSamplerOptionSeed(1),
	)
	study, err := goptuna.CreateStudy(
		"example",
		goptuna.StudyOptionSetDirection(goptuna.StudyDirectionMinimize),
		goptuna.StudyOptionSampler(sampler),
	)
	if err != nil {
		panic(err)
	}

	objective := func(trial goptuna.Trial) (float64, error) {
		x1, _ := trial.SuggestInt("x1", -10, 10)
		x2, _ := trial.SuggestInt("x2", -10, 10)
		fmt.Printf("sampled: %d, %d\n", x1, x2)
		return math.Pow(float64(x1-2), 2) + math.Pow(float64(x2+5), 2), nil
	}

	err = study.Optimize(objective, 1)
	if err != nil {
		panic(err)
	}
}

Output:

sampled: -9, -3

func (*Trial) SuggestUniform 

func (t *Trial) SuggestUniform(name string, low, high float64) (float64, error)

SuggestUniform suggests a value for the continuous parameter.

Example 
package main

import (
	"fmt"
	"math"

	"github.com/c-bata/goptuna"
)

func main() {
	sampler := goptuna.NewRandomSearchSampler(
		goptuna.RandomSearchSamplerOptionSeed(0),
	)
	study, err := goptuna.CreateStudy(
		"example",
		goptuna.StudyOptionSetDirection(goptuna.StudyDirectionMinimize),
		goptuna.StudyOptionSampler(sampler),
	)
	if err != nil {
		panic(err)
	}

	objective := func(trial goptuna.Trial) (float64, error) {
		x1, _ := trial.SuggestUniform("x1", -10, 10)
		x2, _ := trial.SuggestUniform("x2", -10, 10)
		fmt.Printf("sampled: %.3f, %.3f\n", x1, x2)
		return math.Pow(x1-2, 2) + math.Pow(x2+5, 2), nil
	}

	err = study.Optimize(objective, 1)
	if err != nil {
		panic(err)
	}
}

Output:

sampled: 8.904, -5.101

type TrialState 

type TrialState int

TrialState is a state of Trial 

const (
	// TrialStateRunning means Trial is running.
	TrialStateRunning TrialState = iota
	// TrialStateComplete means Trial has been finished without any error.
	TrialStateComplete
	// TrialStatePruned means Trial has been pruned.
	TrialStatePruned
	// TrialStateFail means Trial has failed due to ann uncaught error.
	TrialStateFail
)

func (TrialState) IsFinished 

func (i TrialState) IsFinished() bool

IsFinished returns true if trial is not running.

func (TrialState) String 

func (i TrialState) String() string

type UniformDistribution 

type UniformDistribution struct {
	// High is higher endpoint of the range of the distribution (included in the range).
	High float64 `json:"high"`
	// Low is lower endpoint of the range of the distribution (included in the range).
	Low float64 `json:"low"`
}

UniformDistribution is a uniform distribution in the linear domain.

func (*UniformDistribution) Contains added in v0.0.2 

func (d *UniformDistribution) Contains(ir float64) bool

Contains to check a parameter value is contained in the range of this distribution.

func (*UniformDistribution) Single added in v0.0.2 

func (d *UniformDistribution) Single() bool

Single to test whether the range of this distribution contains just a single value.

func (*UniformDistribution) ToExternalRepr added in v0.0.2 

func (d *UniformDistribution) ToExternalRepr(ir float64) interface{}

ToExternalRepr to convert internal representation of a parameter value into external representation.

func (*UniformDistribution) ToInternalRepr added in v0.0.2 

func (d *UniformDistribution) ToInternalRepr(xr interface{}) float64

ToInternalRepr to convert external representation of a parameter value into internal representation.

Source Files

View all Source files

Directories

Path Synopsis
_examples
concurrency command
simple_random_search command
simple_tpe command
trialnotify command
internal
testutil

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.