Table of Contents

Class FixedTrial

Namespace
OptunaSharp
Assembly
OptunaSharp.dll

A trial class which suggests a fixed value for each parameter. Port of optuna/trial/_fixed.py: FixedTrial.

This object has the same methods as Trial, and it suggests pre-defined parameter values. The parameter values can be determined at the construction of the FixedTrial object. In contrast to Trial, FixedTrial does not depend on Study, and it is useful for deploying optimization results.

public class FixedTrial : BaseTrial
Inheritance
FixedTrial
Inherited Members
Extension Methods

Examples

double Objective(BaseTrial trial)
{
    var x = trial.SuggestFloat("x", -100, 100);
    var y = trial.SuggestCategorical("y", new long[] { -1, 0, 1 });
    return x * x + y;
}

var result = Objective(new FixedTrial(new() { ["x"] = 1.0, ["y"] = 0L }));  // == 1

Constructors

FixedTrial(OrderedDict<string, object?>, int)

Creates an objective replay using the supplied parameter dictionary by reference.

public FixedTrial(OrderedDict<string, object?> @params, int number = 0)

Parameters

params OrderedDict<string, object>

Parameter names mapped to their external values.

number int

Trial number exposed to the objective; defaults to zero.

Remarks

Params contains only parameters that have been requested, not every value supplied to the constructor.

Properties

Constraints

Returns constraint values. The trial is considered feasible when all constraint values are zero or less.

public override OrderedDict<string, double> Constraints { get; }

Property Value

OrderedDict<string, double>

DatetimeStart

Gets the local time at which this replay trial was constructed.

public override DateTime? DatetimeStart { get; }

Property Value

DateTime?

Distributions

Gets the distribution recorded for each suggested parameter.

public override IReadOnlyDictionary<string, BaseDistribution> Distributions { get; }

Property Value

IReadOnlyDictionary<string, BaseDistribution>

Number

Gets the zero-based trial number within the study or replay context.

public override int Number { get; }

Property Value

int

Params

Gets parameters already suggested through this trial, using their external values.

public override IReadOnlyDictionary<string, object?> Params { get; }

Property Value

IReadOnlyDictionary<string, object>

SystemAttrs

Gets the internal metadata recorded on this fixed trial (e.g. the constraint values written by SetConstraint(string, double)). Still part of Optuna 5.0.0's FixedTrial; only the setter was removed (#6834).

public IReadOnlyDictionary<string, object?> SystemAttrs { get; }

Property Value

IReadOnlyDictionary<string, object>

UserAttrs

Gets the user metadata attached to this trial.

public override IReadOnlyDictionary<string, object?> UserAttrs { get; }

Property Value

IReadOnlyDictionary<string, object>

Methods

Report(double, long)

Accepts an intermediate observation without recording it; replay trials do not prune.

public override void Report(double value, long step)

Parameters

value double

Intermediate objective value; ignored by replay trials.

step long

Zero-based reporting step (64-bit, like every trial's); ignored by replay trials.

SetConstraint(string, double)

Set a constraint value for the trial. The trial is considered feasible when all constraint values are zero or less.

public override void SetConstraint(string key, double value)

Parameters

key string

Constraint name; later writes of the same name are ignored with a warning.

value double

Constraint value; zero or negative is feasible and NaN is forbidden.

Exceptions

ValueError

The constraint value is NaN.

SetUserAttr(string, object?)

Updates the local user attribute by name.

public override void SetUserAttr(string key, object? value)

Parameters

key string

Attribute name; an existing attribute is overwritten.

value object

Value retained in this replay record's local attribute dictionary.

ShouldPrune()

Returns false because a replay trial does not run a pruning algorithm.

public override bool ShouldPrune()

Returns

bool

Always false.

SuggestCategorical(string, IEnumerable<CategoricalChoice>)

Replays a stored categorical parameter value for the objective.

public override CategoricalChoice SuggestCategorical(string name, IEnumerable<CategoricalChoice> choices)

Parameters

name string

Parameter name; repeated suggestions refer to the same parameter.

choices IEnumerable<CategoricalChoice>

Nonempty sequence of categorical candidates; order is retained and determines stored indices.

Returns

CategoricalChoice

The stored categorical value.

Exceptions

ValueError

The distribution is invalid, a required stored parameter is missing, or a repeated suggestion changes its distribution kind, logarithmic scale, or categorical choices.

TypeError

A stored or sampled value is not a supported categorical scalar.

ArgumentNullException

The choices sequence is null.

SuggestFloat(string, double, double, double?, bool)

Replays a stored floating-point parameter value for the objective.

public override double SuggestFloat(string name, double low, double high, double? step = null, bool log = false)

Parameters

name string

Parameter name; repeated suggestions refer to the same parameter.

low double

Inclusive lower endpoint of the parameter range.

high double

Inclusive upper endpoint; a stepped range may lower it to the last reachable grid point.

step double?

Positive float grid spacing, or null for a continuous range; cannot be combined with log.

log bool

Whether to sample in the logarithmic domain, which requires a strictly positive lower endpoint.

Returns

double

The stored floating-point value.

Remarks

Numeric values outside the requested range are returned with a warning when replaying stored parameters.

Exceptions

ValueError

The distribution is invalid, a required stored parameter is missing, or a repeated suggestion changes its distribution kind, logarithmic scale, or categorical choices.

TypeError

The stored or sampled value cannot be converted to a float.

FormatException

A stepped bound or step is nonfinite and cannot be parsed as a decimal.

DivideByZeroException

The positive step rounds to zero in decimal arithmetic while aligning the upper endpoint.

SuggestInt(string, long, long, long, bool)

Replays a stored integer parameter value for the objective.

public override long SuggestInt(string name, long low, long high, long step = 1, bool log = false)

Parameters

name string

Parameter name; repeated suggestions refer to the same parameter.

low long

Inclusive lower endpoint of the parameter range.

high long

Inclusive upper endpoint; a stepped range may lower it to the last reachable grid point.

step long

Positive integer grid spacing; must be one for logarithmic sampling.

log bool

Whether to sample in the logarithmic domain, which requires a strictly positive lower endpoint.

Returns

long

The stored integer value.

Remarks

Numeric values outside the requested range are returned with a warning when replaying stored parameters.

Exceptions

ValueError

The distribution is invalid, a required stored parameter is missing, or a repeated suggestion changes its distribution kind, logarithmic scale, or categorical choices.

FormatException

A stored or sampled string is not an integer.

OverflowException

An integer conversion exceeds Int64.

InvalidCastException

The value does not support integer conversion.

See Also

Official Optuna fixed-trial contract.
Edit this page