goptuna

package module
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: Mar 11, 2020 License: MIT Imports: 12 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 optimized 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 following algorithms are implemented:

  • Random Search
  • Tree-structured Parzen Estimators (TPE)
  • Gaussian Process based Bayesian Optimization (GP-BO).
  • Median Stopping Rule (Google Vizier)
  • Optuna flavored Asynchronous Successive Halving Algorithm (ASHA)

See the blog post for more details: Practical bayesian optimization 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 (
    "log"
    "math"

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

// Define an objective function we want to minimize.
func objective(trial goptuna.Trial) (float64, error) {
    // Define a search space of the input values.
    x1, _ := trial.SuggestUniform("x1", -10, 10)
    x2, _ := trial.SuggestUniform("x2", -10, 10)

    // Here is a two-dimensional quadratic function.
    // F(x1, x2) = (x1 - 2)^2 + (x2 + 5)^2
    return math.Pow(x1-2, 2) + math.Pow(x2+5, 2), nil
}

func main() {
    study, err := goptuna.CreateStudy(
        "goptuna-example",
        goptuna.StudyOptionSampler(tpe.NewSampler()),
    )
    if err != nil { ... }

    // Run an objective function 100 times to find a global minimum.
    err = study.Optimize(objective, 100)
    if err != nil { ... }

    // Print the best evaluation value and the parameters.
    // Mathematically, argmin F(x1, x2) is (x1, x2) = (+2, -5).
    v, _ := study.GetBestValue()
    p, _ := study.GetBestParams()
    log.Printf("Best evaluation value=%f (x1=%f, x2=%f)",
        v, p["x1"].(float64), p["x2"].(float64))
}

$ go run main.go
...
2019/08/18 00:54:51 Best evaluation=0.038327 (x1=2.181604, x2=-4.926880)

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

Distributed optimization using RDB storage backend with MySQL

There is no complicated setup for distributed optimization but all Goptuna workers need to use the same RDB storage backend. First, setup MySQL server like following to share the optimization result.

$ cat mysql/my.cnf
[mysqld]
bind-address = 0.0.0.0
default_authentication_plugin=mysql_native_password

$ docker pull mysql:8.0
$ docker run \
  -d \
  --rm \
  -p 3306:3306 \
  --mount type=volume,src=mysql,dst=/etc/mysql/conf.d \
  -e MYSQL_USER=goptuna \
  -e MYSQL_DATABASE=goptuna \
  -e MYSQL_PASSWORD=password \
  -e MYSQL_ALLOW_EMPTY_PASSWORD=yes \
  --name goptuna-mysql \
  mysql:8.0

Then, create a study object using goptuna CLI

$ goptuna create-study --storage mysql://goptuna:password@localhost:3306/yourdb --study yourstudy
yourstudy

$ mysql --host 127.0.0.1 --port 3306 --user goptuna -ppassword -e "SELECT * FROM studies;"
+----------+------------+-----------+
| study_id | study_name | direction |
+----------+------------+-----------+
|        1 | yourstudy  | MINIMIZE  |
+----------+------------+-----------+
1 row in set (0.00 sec)

Finally, run the Goptuna workers which contains following code.

package main

import ...

func main() {
    db, _ := gorm.Open("mysql", "goptuna:password@tcp(localhost:3306)/yourdb?parseTime=true")
    storage := rdb.NewStorage(db)
    defer db.Close()

    study, _ := goptuna.LoadStudy(
        "yourstudy",
        goptuna.StudyOptionStorage(storage),
        ...,
    )
    _ = study.Optimize(objective, 50)
    ...
}

The schema of Goptuna RDB storage backend is compatible with Optuna's one. So you can check optimization result with Optuna's dashboard like following:

$ pip install optuna bokeh mysqlclient
$ optuna dashboard --storage mysql+mysqldb://goptuna:password@127.0.0.1:3306/yourdb --study yourstudy
...

shell script to reproduce this

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.

View Source 
var (
	// ErrUnsupportedSearchSpace represents sampler does not support a given search space.
	ErrUnsupportedSearchSpace = errors.New("unsupported search space")
)
View Source 
var StudyOptionSetLogger = StudyOptionLogger

StudyOptionSetLogger sets Logger. Deprecated: please use StudyOptionLogger instead.

Functions

func DeleteStudy added in v0.2.0 

func DeleteStudy(
	name string,
	storage Storage,
) error

DeleteStudy delete a study object.

func DistributionIsSingle added in v0.2.0 

func DistributionIsSingle(distribution interface{}) (bool, error)

DistributionIsSingle whether the distribution contains just a single value.

func DistributionToJSON added in v0.0.2 

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

DistributionToJSON serialize a distribution to JSON format.

func IntersectionSearchSpace added in v0.2.0 

func IntersectionSearchSpace(study *Study) (map[string]interface{}, error)

IntersectionSearchSpace return return the intersection search space of the Study.

Intersection search space contains the intersection of parameter distributions that have been suggested in the completed trials of the study so far. If there are multiple parameters that have the same name but different distributions, neither is included in the resulting search space (i.e., the parameters with dynamic value ranges are excluded).

func JSONToDistribution added in v0.0.2 

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

JSONToDistribution deserialize a distribution in JSON format.

func ToExternalRepresentation added in v0.0.4 

func ToExternalRepresentation(distribution interface{}, ir float64) (interface{}, error)

ToExternalRepresentation converts to external representation

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.

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.

type Distribution 

type Distribution interface {
	// 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"`
	InternalParams     map[string]float64     `json:"internal_params"`
	Params             map[string]interface{} `json:"params"`
	Distributions      map[string]interface{} `json:"distributions"`
	UserAttrs          map[string]string      `json:"user_attrs"`
	SystemAttrs        map[string]string      `json:"system_attrs"`
}

FrozenTrial holds the status and results of a Trial.

func (FrozenTrial) GetLatestStep added in v0.2.0 

func (t FrozenTrial) GetLatestStep() (step int, exist bool)

GetLatestStep returns the latest step in intermediate values.

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) CloneTrial added in v0.3.0 

func (s *InMemoryStorage) CloneTrial(studyID int, baseTrial FrozenTrial) (int, error)

CloneTrial creates new Trial from the given base Trial.

func (*InMemoryStorage) CreateNewStudy added in v0.2.0 

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

CreateNewStudy creates study and returns studyID.

Example 
package main

import (
	"fmt"

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

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

}

Output:

1

func (*InMemoryStorage) CreateNewTrial added in v0.2.0 

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

CreateNewTrial creates trial and returns trialID.

func (*InMemoryStorage) DeleteStudy added in v0.2.0 

func (s *InMemoryStorage) DeleteStudy(studyID int) error

DeleteStudy deletes a study.

func (*InMemoryStorage) GetAllStudySummaries added in v0.0.2 

func (s *InMemoryStorage) GetAllStudySummaries() ([]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.CreateNewStudy("")
	if err != nil {
		panic(err)
	}
	trialID, err := storage.CreateNewTrial(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]string, 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]string, 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]string, 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]string, 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 string) 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.CreateNewStudy("")
	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 string) 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.CreateNewStudy("")
	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. While sets the intermediate value, trial.Value is also updated.

func (*InMemoryStorage) SetTrialParam 

func (s *InMemoryStorage) SetTrialParam(
	trialID int,
	paramName string,
	paramValueInternal float64,
	distribution interface{}) 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 string) 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.CreateNewStudy("")
	if err != nil {
		panic(err)
	}
	trialID, err := storage.CreateNewTrial(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 string) 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.CreateNewStudy("")
	if err != nil {
		panic(err)
	}
	trialID, err := storage.CreateNewTrial(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.

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.

type Logger added in v0.1.0 

type Logger interface {
	Debug(msg string, fields ...interface{})
	Info(msg string, fields ...interface{})
	Warn(msg string, fields ...interface{})
	Error(msg string, fields ...interface{})
}

Logger is the interface for logging messages. If you want to log nothing, please set Logger as nil. If you want to print more verbose logs, it might StudyOptionSetTrialNotifyChannel option are useful.

type LoggerLevel added in v0.1.0 

type LoggerLevel int

LoggerLevel represents Level is a logging priority. Higher levels are more important. 

const (
	// LoggerLevelDebug logs are typically voluminous, and are usually disabled in production.
	LoggerLevelDebug LoggerLevel = iota - 1
	// LoggerLevelInfo is the default logging priority.
	LoggerLevelInfo
	// LoggerLevelWarn logs are more important than Info, but don't need individual human review.
	LoggerLevelWarn
	// LoggerLevelError logs are high-priority.
	LoggerLevelError
)

type Pruner added in v0.0.3 

type Pruner interface {
	// Prune judge whether the trial should be pruned at the given step.
	Prune(study *Study, trial FrozenTrial) (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 RelativeSampler added in v0.2.0 

type RelativeSampler interface {
	// SampleRelative samples multiple dimensional parameters in a given search space.
	SampleRelative(*Study, FrozenTrial, map[string]interface{}) (map[string]float64, error)
}

RelativeSampler is the interface for sampling algorithms that use relationship between parameters such as Gaussian Process and CMA-ES.

This interface is called once at the beginning of each trial, i.e., right before the evaluation of the objective function.

type Sampler 

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

Sampler is the interface for sampling algorithms that do not use relationship between parameters such as random sampling and TPE.

Note that if study object has RelativeSampler, this interface is used only for parameters that are not sampled by RelativeSampler.

type StdLogger added in v0.1.0 

type StdLogger struct {
	Logger *log.Logger
	Level  LoggerLevel
	Color  bool
}

StdLogger wraps 'log' standard library.

func (*StdLogger) Debug added in v0.1.0 

func (l *StdLogger) Debug(msg string, fields ...interface{})

Debug logs a message at LoggerLevelDebug which are usually disabled in production.

func (*StdLogger) Error added in v0.1.0 

func (l *StdLogger) Error(msg string, fields ...interface{})

Error logs a message at LoggerLevelError which are high-priority.

func (*StdLogger) Info added in v0.1.0 

func (l *StdLogger) Info(msg string, fields ...interface{})

Info logs a message at LoggerLevelInfo. The message includes any fields passed at the log site, as well as any fields accumulated on the logger.

func (*StdLogger) Warn added in v0.1.0 

func (l *StdLogger) Warn(msg string, fields ...interface{})

Warn logs a message at LoggerLevelWarn which more important than Info, but don't need individual human review.

type Storage 

type Storage interface {
	// Basic study manipulation
	CreateNewStudy(name string) (int, error)
	DeleteStudy(studyID int) error
	SetStudyDirection(studyID int, direction StudyDirection) error
	SetStudyUserAttr(studyID int, key string, value string) error
	SetStudySystemAttr(studyID int, key string, value string) 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]string, error)
	GetStudySystemAttrs(studyID int) (map[string]string, error)
	GetAllStudySummaries() ([]StudySummary, error)
	// Basic trial manipulation
	CreateNewTrial(studyID int) (int, error)
	CloneTrial(studyID int, baseTrial FrozenTrial) (int, error)
	SetTrialValue(trialID int, value float64) error
	SetTrialIntermediateValue(trialID int, step int, value float64) error
	SetTrialParam(trialID int, paramName string, paramValueInternal float64,
		distribution interface{}) error
	SetTrialState(trialID int, state TrialState) error
	SetTrialUserAttr(trialID int, key string, value string) error
	SetTrialSystemAttr(trialID int, key string, value string) 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]string, error)
	GetTrialSystemAttrs(trialID int) (map[string]string, 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
	RelativeSampler RelativeSampler
	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 LoadStudy added in v0.0.4 

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

LoadStudy loads an existing study.

func (*Study) Direction 

func (s *Study) Direction() StudyDirection

Direction returns the direction of objective function value

func (*Study) EnqueueTrial added in v0.3.0 

func (s *Study) EnqueueTrial(internalParams map[string]float64) error

EnqueueTrial to enqueue a trial with given parameter values. You can fix the next sampling parameters which will be evaluated in your objective function.

This is an EXPERIMENTAL API and may be changed in the future. Currently EnqueueTrial only accepts internal representations. This means that you need to encode categorical parameter to its index number. Furthermore, please caution that there is a concurrency problem in RDB storage like https://github.com/optuna/optuna/pull/1014.

Example 
package main

import (
	"fmt"
	"math"

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

func main() {
	study, _ := goptuna.CreateStudy(
		"example",
		goptuna.StudyOptionLogger(nil),
	)

	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
	}

	study.EnqueueTrial(map[string]float64{"x1": 2, "x2": -5})

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

	trials, err := study.GetTrials()
	if err != nil {
		panic(err)
	}

	fmt.Printf("x1: %.3f\n", trials[0].Params["x1"].(float64))
	fmt.Printf("x2: %.3f\n", trials[0].Params["x2"].(float64))

}

Output:

x1: 2.000
x2: -5.000

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) GetSystemAttrs added in v0.0.4 

func (s *Study) GetSystemAttrs() (map[string]string, error)

GetSystemAttrs to store the value for the system.

func (*Study) GetTrials 

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

GetTrials returns all trials in this study.

func (*Study) GetUserAttrs added in v0.0.4 

func (s *Study) GetUserAttrs() (map[string]string, error)

GetUserAttrs to store the value for the user.

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.StudyOptionSampler(sampler),
		goptuna.StudyOptionLogger(nil),
	)

	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"].(float64))
	fmt.Printf("x2: %.3f\n", params["x2"].(float64))
}

Output:

Best trial: 0.03833
x1: 2.182
x2: -4.927

func (*Study) SetSystemAttr added in v0.0.4 

func (s *Study) SetSystemAttr(key, value string) error

SetSystemAttr to store the value for the system.

func (*Study) SetUserAttr added in v0.0.4 

func (s *Study) SetUserAttr(key, value string) error

SetUserAttr to store the value for the user.

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 StudyOptionIgnoreError added in v0.1.0 

func StudyOptionIgnoreError(ignore bool) StudyOption

StudyOptionIgnoreError is an option to continue even if it receive error while running Optimize method.

func StudyOptionLoadIfExists added in v0.2.0 

func StudyOptionLoadIfExists(loadIfExists bool) StudyOption

StudyOptionLoadIfExists to load the study if exists.

func StudyOptionLogger added in v0.1.0 

func StudyOptionLogger(logger Logger) StudyOption

StudyOptionLogger sets Logger.

func StudyOptionPruner added in v0.0.3 

func StudyOptionPruner(pruner Pruner) StudyOption

StudyOptionPruner sets the pruner object.

func StudyOptionRelativeSampler added in v0.2.0 

func StudyOptionRelativeSampler(sampler RelativeSampler) StudyOption

StudyOptionRelativeSampler sets the relative sampler 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 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]string `json:"user_attrs"`
	SystemAttrs   map[string]string `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) GetContext added in v0.0.4 

func (t *Trial) GetContext() context.Context

GetContext returns a context which is registered at 'study.WithContext()'.

func (*Trial) GetSystemAttrs added in v0.0.4 

func (t *Trial) GetSystemAttrs() (map[string]string, error)

GetSystemAttrs to store the value for the system.

func (*Trial) GetUserAttrs added in v0.0.4 

func (t *Trial) GetUserAttrs() (map[string]string, error)

GetUserAttrs to store the value for the user.

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) SetSystemAttr added in v0.0.4 

func (t *Trial) SetSystemAttr(key, value string) error

SetSystemAttr to store the value for the system.

func (*Trial) SetUserAttr added in v0.0.4 

func (t *Trial) SetUserAttr(key, value string) error

SetUserAttr to store the value for the user.

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) SuggestDiscreteUniform added in v0.0.4 

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

SuggestDiscreteUniform suggests a value from a discrete uniform distribution.

func (*Trial) SuggestInt 

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

SuggestInt suggests an integer parameter.

func (*Trial) SuggestLogUniform added in v0.0.4 

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

SuggestLogUniform suggests a value from a uniform distribution in the log domain.

func (*Trial) SuggestUniform 

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

SuggestUniform suggests a value from a uniform distribution.

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 an uncaught error.
	TrialStateFail
	// TrialStateWaiting means Trial has been stopped, but may be resuming.
	TrialStateWaiting
)

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.

Source Files

View all Source files

Directories

Path Synopsis
_benchmarks
tpe_solver command
_examples
concurrency command
signalhandling command
simple_rdb command
simple_tpe command
trialnotify command
cmd
createstudy
deletestudy
internal
random
sqlalchemy
stats
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.