> ## Documentation Index
> Fetch the complete documentation index at: https://systematica.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Utils

> systematica.tuners.optuna_.utils

## `check_direction`

```python theme={null}
check_direction(
    value: str | list[str],
)
```

Validate optimization directions.

**Parameters**:

| Name    | Type  | Default | Description              |
| ------- | ----- | ------- | ------------------------ |
| `value` | `str` | `--`    | \| list\[str] Direction. |

**Raises**:

| Type         | Description                                   |
| ------------ | --------------------------------------------- |
| `ValueError` | If direction is not "maximize" or "minimize". |
| `TypeError`  | If direction is not a string or a list        |

## `BaseOptunaTrial`

```python theme={null}
BaseOptunaTrial()
```

Base Optuna trial class used to suggest value.

### Ancestors

* `abc.ABC`

### Descendants

* `systematica.tuners.optuna_.utils.Categorical`
* `systematica.tuners.optuna_.utils.Float`
* `systematica.tuners.optuna_.utils.Int`
* `systematica.tuners.optuna_.utils.Param`

### Methods

#### `suggest`

```python theme={null}
suggest(
    self,
    trial: optuna.trial._trial.Trial,
) ‑> Any
```

Suggest a value for the parameter.

**Parameters**:

| Name    | Type           | Default | Description              |
| ------- | -------------- | ------- | ------------------------ |
| `trial` | `optuna.Trial` | `--`    | The Optuna trial object. |

**Returns**:

| Type     | Description                          |
| -------- | ------------------------------------ |
| `tp.Any` | A suggested value for the parameter. |

## `Float`

```python theme={null}
Float(
    name: str,
    low: float,
    high: float,
    step: float | None = None,
    log: bool = False,
)
```

Class that represents a float Optuna suggestion.

Method generated by attrs for class Float.

### Ancestors

* `systematica.tuners.optuna_.utils.BaseOptunaTrial`
* `abc.ABC`

### Instance variables

* `high: float`: Upper endpoint of the range of suggested values. `high` is included in  the range. `high` must be greater than or equal to `low`.

* `log: bool`: A flag to sample the value from the log domain or not. If `log` is `True`, the value is sampled from the range in the log  domain. Otherwise, the value is sampled from the range in the linear  domain.

* `low: float`: Lower endpoint of the range of suggested values. `low` is included in  the range. `low` must be less than or equal to `high`. If `log`  is `True`, `low` must be larger than 0.

* `name: str`: A parameter name.

* `step: float | None`: A step of discretization.

### Methods

#### `suggest`

```python theme={null}
suggest(
    self,
    trial: optuna.trial._trial.Trial,
) ‑> float
```

Suggest a value for the floating point parameter.

**Parameters**:

| Name    | Type           | Default | Description              |
| ------- | -------------- | ------- | ------------------------ |
| `trial` | `optuna.Trial` | `--`    | The Optuna trial object. |

**Returns**:

| Type    | Description              |
| ------- | ------------------------ |
| `float` | A suggested float value. |

## `Int`

```python theme={null}
Int(
    name: str,
    low: int,
    high: int,
    step: int = 1,
    log: bool = False,
)
```

Class that represents an integer Optuna suggestion.

Method generated by attrs for class Int.

### Ancestors

* `systematica.tuners.optuna_.utils.BaseOptunaTrial`
* `abc.ABC`

### Instance variables

* `high: int`: Upper endpoint of the range of suggested values. `high` is included in  the range. `high` must be greater than or equal to `low`.

* `log: bool`: A flag to sample the value from the log domain or not. If `log` is true, the value is sampled from the range in the log domain. Otherwise, the value is sampled from the range in the linear domain.

* `low: int`: Lower endpoint of the range of suggested values. `low` is included in  the range. `low` must be less than or equal to `high`. If `log` is  `True`, `low` must be larger than 0.

* `name: str`: A parameter name.

* `step: int`: A step of discretization.

### Methods

#### `suggest`

```python theme={null}
suggest(
    self,
    trial: optuna.trial._trial.Trial,
) ‑> int
```

Suggest a value for the integer parameter.

The value is sampled from the integers in :math:`[\mathsf{low}, \mathsf{high}]`.

**Parameters**:

| Name    | Type           | Default | Description              |
| ------- | -------------- | ------- | ------------------------ |
| `trial` | `optuna.Trial` | `--`    | The Optuna trial object. |

**Returns**:

| Type  | Description            |
| ----- | ---------------------- |
| `int` | A suggested int value. |

## `Categorical`

```python theme={null}
Categorical(
    name: str,
    choices: Sequence[bool | int | float | str | None],
)
```

Class that represents a categorical Optuna suggestion.

Method generated by attrs for class Categorical.

### Ancestors

* `systematica.tuners.optuna_.utils.BaseOptunaTrial`
* `abc.ABC`

### Instance variables

* `choices: Sequence[bool | int | float | str | None]`: Parameter value candidates.

* `name: str`: A parameter name.

### Methods

#### `suggest`

```python theme={null}
suggest(
    self,
    trial: optuna.trial._trial.Trial,
) ‑> bool | int | float | str | None
```

Suggest a value for the categorical parameter.

The value is sampled from `choices`.

**Parameters**:

| Name    | Type           | Default | Description              |
| ------- | -------------- | ------- | ------------------------ |
| `trial` | `optuna.Trial` | `--`    | The Optuna trial object. |

**Returns**:

| Type                                         | Description                    |
| -------------------------------------------- | ------------------------------ |
| `optuna.distributions.CategoricalChoiceType` | A suggested categorical value. |

## `Param`

```python theme={null}
Param(
    name: str,
    choices: Sequence[bool | int | float | str | None] = None,
    low: int = None,
    high: int = None,
    step: int = 1,
    log: bool = False,
)
```

Class that represents a any Optuna suggestion.

Method generated by attrs for class Param.

### Ancestors

* `systematica.tuners.optuna_.utils.BaseOptunaTrial`
* `abc.ABC`

### Instance variables

* `choices: Sequence[bool | int | float | str | None]`: Parameter value candidates.

* `high: int`: Upper endpoint of the range of suggested values. `high` is included in  the range. `high` must be greater than or equal to `low`.

* `log: bool`: A flag to sample the value from the log domain or not. If `log` is true, the value is sampled from the range in the log domain. Otherwise, the value is sampled from the range in the linear domain.

* `low: int`: Lower endpoint of the range of suggested values. `low` is included in  the range. `low` must be less than or equal to `high`. If `log` is  `True`, `low` must be larger than 0.

* `name: str`: A parameter name.

* `step: int`: A step of discretization.

### Methods

#### `suggest`

```python theme={null}
suggest(
    self,
    trial: optuna.trial._trial.Trial,
) ‑> bool | int | float | str | None
```

Suggest a value for any parameter.

**Parameters**:

| Name    | Type           | Default | Description              |
| ------- | -------------- | ------- | ------------------------ |
| `trial` | `optuna.Trial` | `--`    | The Optuna trial object. |

**Returns**:

| Type                                                         | Description        |
| ------------------------------------------------------------ | ------------------ |
| `int \| float \| optuna.distributions.CategoricalChoiceType` | A suggested value. |