Swiftuna

https://zuidvolt.github.io/swiftuna/documentation/swiftuna
Admin
Swiftuna provides Swift bindings for the Optuna hyperparameter optimization framework, enabling...
Tokens:66,087
Snippets:886
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install and run Optuna Dashboard

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/storagebackend/sqlite%28path%3A%29

Commands to install the Optuna Dashboard and visualize studies stored in a SQLite database.

```bash
pip install optuna-dashboard
optuna-dashboard sqlite:///experiments.db
```

--------------------------------

### Enqueueing a Trial Configuration

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/study/enqueue%28_%3Auserattrs%3A%29

Example of calling the enqueue method with specific parameter values.

```swift
try study.enqueue(["learning_rate": 0.01, "batch_size": 32])
```

--------------------------------

### Usage Examples for suggest(_:choices:)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/trial/suggest%28_%3Achoices%3A%29

Demonstrates how to use the method with enums, integers, and strings to suggest parameter values.

```swift
enum Activation: String, CaseIterable, Sendable { case relu, gelu, silu }
let activation = try trial.suggest("activation", choices: Activation.allCases) // Inferred as Activation
let batchSize = try trial.suggest("batch_size", choices: [32, 64, 128])         // Inferred as Int
let optimizer = try trial.suggest("optimizer", choices: ["adamw", "sgd", "adam"])
```

--------------------------------

### Usage Example for suggest(_:in:step:log:)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/trial/suggest%28_%3Ain%3Astep%3Alog%3A%29-6w64u

Demonstrates how to use the suggest method to retrieve parameter values for batch size and epochs.

```swift
let batchSize = try trial.suggest("batch_size", in: 16...128, step: 16)
let epochs = try trial.suggest("epochs", in: 5...50)
```

--------------------------------

### Usage Example for suggest(_:in:step:log:)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/trial/suggest%28_%3Ain%3Astep%3Alog%3A%29-5lvuq

Demonstrates how to suggest a learning rate using a log scale and a weight decay value with a discretization step.

```swift
let lr = try trial.suggest("learning_rate", in: 1e-5...1e-1, log: true)
let weightDecay = try trial.suggest("weight_decay", in: 0.0...0.1, step: 0.01)
```

--------------------------------

### Usage Example for setConstraint(_:value:)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/trial/setconstraint%28_%3Avalue%3A%29-8rb3y

Demonstrates defining a custom ConstraintKey and applying it to a trial instance.

```swift
extension ConstraintKey { static let maxLatency = ConstraintKey("max_latency_ms") }
try trial.setConstraint(.maxLatency, value: latencyMs - 25.0)
```

--------------------------------

### Usage of prune(reason:)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/trial/prune%28reason%3A%29

Example showing how to check if a trial should be pruned and then calling the prune method with a specific reason.

```swift
if try trial.shouldPrune {
    try trial.prune(reason: "Validation loss diverged at epoch \(epoch)")
}
```

--------------------------------

### Filtering Trials Example

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/swift/sequence/filter%28where%3Aequals%3A%29

Usage example demonstrating how to filter study trials by a specific architecture attribute.

```swift
let resnetTrials = study.trials.filter(where: .architecture, equals: "ResNet-50")
```

--------------------------------

### Usage Example for float(_:)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/persistedtrial/float%28_%3A%29

Demonstrates retrieving a float value from a trial with a fallback default value.

```swift
let lr: Float = bestTrial.float("lr") ?? 0.001
```

--------------------------------

### Initialize PatientPruner with a wrapped pruner

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/patientpruner

Example showing how to wrap a MedianPruner with a patience grace period.

```swift
// Tolerate up to 3 consecutive prune signals from MedianPruner before actually stopping
let base = MedianPruner(nStartupTrials: 5)
let pruner = PatientPruner(wrappedPruner: base, patience: 3)
```

--------------------------------

### Injecting a Baseline Trial

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/study/addtrial%28_%3A%29

Example showing the creation of a PersistedTrial and its injection into an existing study instance.

```swift
let baseline = PersistedTrial(
    number: 0,
    state: .complete,
    values: [0.42],
    params: ["learning_rate": 0.001, "batch_size": 64]
)
try study.addTrial(baseline)
```

--------------------------------

### Execute optimization with trial limit

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/study/optimize%28ntrials%3Atimeout%3Aobjective%3A%29-3gyl5

Example usage of the optimize method to minimize a quadratic function over 100 trials.

```swift
try study.optimize(nTrials: 100) { trial in
    let x = try trial.suggest("x", in: -10.0...10.0)
    return x * x
}
```

--------------------------------

### ConstraintKey Usage

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/constraintkey

Example of defining and applying constraints within an optimization trial using dot-syntax.

```APIDOC
## Defining and Applying Constraints

### Description
Define custom constraint keys as static properties on ConstraintKey and assign violation magnitudes within the trial optimization block.

### Example
```swift
extension ConstraintKey {
    static let maxLatency = ConstraintKey("max_latency_ms")
    static let maxMemory = ConstraintKey("memory_mb_limit")
}

try study.optimize(nTrials: 100) { trial in
    let batchSize = try trial.suggest("batch_size", in: 16...512)
    let (loss, memMB, latencyMs) = evaluateModel(batchSize: batchSize)

    // Enforce memMB <= 4096 and latencyMs <= 50.0:
    trial[constraint: .maxMemory] = memMB - 4096.0
    trial[constraint: .maxLatency] = latencyMs - 50.0

    return loss
}
```
```

--------------------------------

### Install Swiftuna via Package.swift

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/gettingstarted

Add Swiftuna as a dependency in your Package.swift file to include it in your project.

```swift
// swift-tools-version: 6.0
import PackageDescription


let package = Package(
    name: "MyOptimizer",
    platforms: [.macOS(.v13), .iOS(.v16)],
    dependencies: [
        .package(url: "https://github.com/ZuidVolt/swiftuna.git", from: "main")
    ],
    targets: [
        .executableTarget(
            name: "MyOptimizer",
            dependencies: [
                .product(name: "Swiftuna", package: "swiftuna")
            ]
        )
    ]
)
```

--------------------------------

### Visualize SQLite studies with Optuna Dashboard

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/storageanddashboard

Install the dashboard via pip and point it to the SQLite database file to view optimization progress in a browser.

```bash
# 1. Install optuna-dashboard via pip
pip install optuna-dashboard


# 2. Start the dashboard server pointing to your Swiftuna database
optuna-dashboard sqlite:///experiments.db
```

--------------------------------

### Optimize with a Trial

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/trial

Example of using a Trial within an optimization study to suggest hyperparameters and evaluate a model.

```swift
study.optimize(nTrials: 50) { trial in
    let lr = try trial.suggest("lr", in: 1e-4...1e-1, log: true)
    let layers = try trial.suggest("layers", in: 1...5)
    return evaluateModel(layers: layers, lr: lr)
}
```

--------------------------------

### Example Usage of paramImportances

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/study/paramimportances%28normalize%3Aparams%3A%29

Demonstrates how to retrieve and iterate over hyperparameter importance scores from a study instance.

```swift
if case .success(let importances) = study.paramImportances() {
    for (param, score) in importances.sorted(by: { $0.value > $1.value }) {
        print("\(param): \(String(format: "%.2f%%", score * 100))")
    }
}
```

--------------------------------

### Retrieving the Best Trial

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/swift/sequence/best%28direction%3A%29

Example usage of the best() method on a sequence of trials filtered by optimizer choice.

```swift
let bestAdam = study.trials.completed()
    .filter(param: "optimizer", equals: OptimizerChoice.adam)
    .best()
```

--------------------------------

### Example usage of loadStudy

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/loadstudy%28name%3Astorage%3Asampler%3Apruner%3A%29

Demonstrates loading a study named 'production_model' from a SQLite database using a TPE sampler.

```swift
let study = try Swiftuna.loadStudy(
    name: "production_model",
    storage: .sqlite(path: "experiments.db"),
    sampler: TPESampler()
)
```

--------------------------------

### Create and Add a Trial

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/createtrial%28state%3Avalue%3Avalues%3Aparams%3Auserattrs%3Aconstraints%3Aintermediatevalues%3Adatetimestart%3Adatetimecomplete%3A%29

Example of creating a completed trial with a specific objective value and hyperparameter, then adding it to a study.

```swift
let trial = Swiftuna.createTrial(
    state: .complete,
    value: 0.15,
    params: ["learning_rate": 0.001]
)
try study.addTrial(trial)
```

--------------------------------

### startSpan(name:attributes:)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/nooptelemetrytracer/startspan%28name%3Aattributes%3A%29

Starts a new telemetry span with the specified name and initial attributes.

```APIDOC
## startSpan(name:attributes:)

### Description
Starts a new telemetry span with the specified name and initial attributes.

### Signature
`func startSpan(name: String, attributes: [String : String]) -> any TelemetrySpan`

### Parameters
- **name** (String) - Name of the operation being traced (e.g. "swiftuna.trial").
- **attributes** ([String : String]) - Initial key-value metadata attached to the span.

### Return Value
- **any TelemetrySpan** - An active TelemetrySpan handle.
```

--------------------------------

### Usage of param(_:) for Activation enum

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/persistedtrial/param%28_%3A%29

Example showing how to retrieve an Activation enum value from a trial using the param method.

```swift
let act: Activation? = bestTrial.param("activation")
```

--------------------------------

### startSpan(name:attributes:) method signature

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/nooptelemetrytracer/startspan%28name%3Aattributes%3A%29

Defines the method signature for starting a telemetry span with a name and string-based attributes.

```swift
func startSpan(
    name: String,
    attributes: [String : String]
) -> any TelemetrySpan
```

--------------------------------

### Register and use the global telemetry tracer

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/telemetryandobservability

Register a custom tracer globally before starting optimization runs and restore the default no-op tracer afterward to ensure proper cleanup.

```swift
// 1. Register tracer globally
SwiftunaTelemetry.shared.registerTracer(ConsoleLoggingTracer())


// 2. Run optimization study with automatic instrumentation
let study = try Swiftuna.createStudy(name: "monitored_study")
try study.optimize(nTrials: 20) { trial in
    let x = try trial.suggest("x", in: -5.0...5.0)
    return x * x
}


// 3. Restore default no-op tracer when finished
SwiftunaTelemetry.shared.registerTracer(nil)
```

--------------------------------

### init(seed:)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/qmcsampler/init%28seed%3A%29

Initializes a new instance of the QMC Sobol sequence sampler.

```APIDOC
## init(seed:)

### Description
Creates a QMC Sobol sequence sampler.

### Signature
`init(seed: UInt64? = nil)`

### Parameters
- **seed** (UInt64?) - Optional - Optional seed for the fallback random sampler used when parameters fall outside the joint search space or when scrambling is enabled.
```

--------------------------------

### Initialize QMCSampler and Study

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/qmcsampler

Demonstrates creating a QMCSampler instance with a seed and using it to initialize a Swiftuna study.

```swift
let sampler = QMCSampler(seed: 42)
let study = try Swiftuna.createStudy(
    name: "qmc_exploration",
    sampler: sampler
)
```

--------------------------------

### Initialize and use NSGAIISampler

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/nsgaiisampler

Demonstrates creating an NSGA-II sampler with specific population and crossover parameters, then using it within a multi-objective study optimization.

```swift
let sampler = NSGAIISampler(populationSize: 40, crossoverProb: 0.9, seed: 42)
let study = try Swiftuna.createStudy(directions: [.minimize, .minimize], sampler: sampler)
try study.optimize(nTrials: 100) { trial in
    let x = try trial.suggest("x", in: -5.0...5.0)
    let y = try trial.suggest("y", in: -5.0...5.0)
    return [x * x, (x - 2.0) * (x - 2.0) + y * y]
}
```

--------------------------------

### init(searchSpace:seed:)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/gridsampler/init%28searchspace%3Aseed%3A%29-48zt9

Initializes a GridSampler with raw [Double] domains.

```APIDOC
## init(searchSpace:seed:)

### Description
Initializes a GridSampler with raw [Double] domains.

### Signature
`init(searchSpace: [String : [Double]], seed: UInt64? = nil)`

### Parameters
- **searchSpace** ([String : [Double]]) - Required - Dictionary mapping parameter names to their list of floating-point values.
- **seed** (UInt64?) - Optional - Optional seed for deterministic shuffling.
```

--------------------------------

### init(percentile:nStartupTrials:nWarmupSteps:intervalSteps:)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/percentilepruner

Initializes a new PercentilePruner instance with specified threshold and timing parameters.

```APIDOC
## init(percentile: Double, nStartupTrials: Int, nWarmupSteps: Int, intervalSteps: Int)

### Description
Initializes a Percentile pruner to keep trials whose intermediate values fall in the top percentile of historical trials.

### Parameters
- **percentile** (Double) - Target percentile threshold between 0.0 and 100.0.
- **nStartupTrials** (Int) - Number of initial trials run before pruning decisions take effect.
- **nWarmupSteps** (Int) - Number of initial steps within each trial before pruning evaluation begins.
- **intervalSteps** (Int) - Step interval at which pruning decisions are evaluated.
```

--------------------------------

### Define Optimization Direction

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/direction

Examples of configuring study optimization goals for single and multi-objective scenarios.

```swift
let study = try Swiftuna.createStudy(
    name: "loss_minimization",
    direction: .minimize
)
```

```swift
let study = try Swiftuna.createStudy(
    name: "accuracy_vs_latency",
    directions: [.maximize, .minimize]
)
```

--------------------------------

### init(searchSpace:seed:)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/gridsampler/init%28searchspace%3Aseed%3A%29-1l3re

Initializes a GridSampler with typed GridSampler.ValueList domains.

```APIDOC
## init(searchSpace:seed:)

### Description
Initializes a GridSampler with typed `GridSampler.ValueList` domains.

### Signature
`init(searchSpace: [String : GridSampler.ValueList], seed: UInt64? = nil)`

### Parameters
- **searchSpace** ([String : GridSampler.ValueList]) - Required - Dictionary mapping parameter names to their list of valid discrete values.
- **seed** (UInt64?) - Optional - Optional seed for deterministic shuffling.
```

--------------------------------

### PartialRangeFrom Operator Definition

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/parametervalue/%27...%28_%3A%29-8ko5m

Defines the static method for creating a range starting from a minimum value.

```swift
static func ... (minimum: Self) -> PartialRangeFrom<Self>
```

--------------------------------

### init(id:name:directions:userAttrs:systemAttrs:trialCount:)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/studysummary/init%28id%3Aname%3Adirections%3Auserattrs%3Asystemattrs%3Atrialcount%3A%29

Initializes a new study summary record with the specified ID, name, directions, and optional attributes.

```APIDOC
## init(id:name:directions:userAttrs:systemAttrs:trialCount:)

### Description
Initializes a study summary record.

### Signature
```swift
init(
    id: Int,
    name: String,
    directions: [Direction],
    userAttrs: [String : String] = [:],
    systemAttrs: [String : String] = [:],
    trialCount: Int = 0
)
```

### Parameters
- **id** (Int) - Unique integer study ID.
- **name** (String) - Unique study name.
- **directions** ([Direction]) - Array of optimization directions.
- **userAttrs** ([String : String]) - Key-value user attributes. Defaults to [:].
- **systemAttrs** ([String : String]) - Key-value system attributes. Defaults to [:].
- **trialCount** (Int) - Total trial count. Defaults to 0.
```

--------------------------------

### init(populationSize:mutationProb:crossoverProb:swappingProb:seed:)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/nsgaiisampler

Initializes a new instance of the NSGAIISampler with specified genetic algorithm parameters.

```APIDOC
## init(populationSize: Int, mutationProb: Double?, crossoverProb: Double, swappingProb: Double, seed: UInt64?)

### Description
Initializes an NSGA-II multi-objective genetic sampler with the provided configuration parameters.

### Parameters
- **populationSize** (Int) - Required - Number of candidate individuals maintained in each generation.
- **mutationProb** (Double?) - Optional - Probability of mutating each parameter of a candidate individual.
- **crossoverProb** (Double) - Required - Probability of performing crossover between two parent individuals.
- **swappingProb** (Double) - Required - Probability of swapping each parameter value during genetic crossover.
- **seed** (UInt64?) - Optional - Optional seed for deterministic reproducibility.
```

--------------------------------

### Iterate over study summaries

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/storagebackend/studies%28%29

Demonstrates initializing a SQLite storage backend and iterating through the returned study summaries.

```swift
let storage = StorageBackend.sqlite(path: "experiments.db")
for summary in try storage.studies() {
    print("Study '\(summary.name)' has \(summary.trialCount) trials")
}
```

--------------------------------

### Initialize and use HyperbandPruner

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/hyperbandpruner

Demonstrates creating a HyperbandPruner instance and assigning it to a study.

```swift
let pruner = HyperbandPruner(minResource: 1, maxResource: 81, reductionFactor: 3)
let study = try Swiftuna.createStudy(pruner: pruner)
```

--------------------------------

### Retrieving a String Value

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/persistedtrial/string%28_%3A%29

Example of using the string(_:) method with a nil-coalescing operator to provide a default value.

```swift
let tag: String = bestTrial.string("tag") ?? "default"
```

--------------------------------

### Create and Optimize a Study

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/study

Demonstrates initializing a study and running an optimization loop with parameter suggestions.

```swift
let study = try Swiftuna.createStudy(name: "hyperparameter_search", direction: .minimize)
try study.optimize(nTrials: 100) { trial in
    let x = try trial.suggest("x", in: -5.0...5.0)
    return x * x
}
print("Best value: \(try study.bestValue)")
```

--------------------------------

### Define subscript(userAttr:) signature

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/study/subscript%28userattr%3A%29

Defines the subscript signature for getting and setting user attributes by key.

```swift
subscript(userAttr key: String) -> String? { get set }
```

--------------------------------

### init(populationSize:mutationProb:crossoverProb:swappingProb:seed:)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/nsgaiisampler/init%28populationsize%3Amutationprob%3Acrossoverprob%3Aswappingprob%3Aseed%3A%29

Initializes an NSGA-II multi-objective genetic sampler with the specified genetic algorithm parameters.

```APIDOC
## init(populationSize:mutationProb:crossoverProb:swappingProb:seed:)

### Description
Initializes an NSGA-II multi-objective genetic sampler.

### Parameters
- **populationSize** (Int) - Optional - Number of individuals per generation. Defaults to 50.
- **mutationProb** (Double?) - Optional - Probability of mutating parameters. If nil, defaults to 1.0 / nParams.
- **crossoverProb** (Double) - Optional - Probability of crossover between two parents. Defaults to 0.9.
- **swappingProb** (Double) - Optional - Probability of swapping parameter values during crossover. Defaults to 0.5.
- **seed** (UInt64?) - Optional - Optional seed for reproducibility.
```

--------------------------------

### init(minResource:reductionFactor:minEarlyStoppingRate:bootstrapCount:trialFilter:)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/successivehalvingpruner/init%28minresource%3Areductionfactor%3Aminearlystoppingrate%3Abootstrapcount%3Atrialfilter%3A%29

Initializes an Asynchronous Successive Halving (ASHA) pruner with configurable resource and trial parameters.

```APIDOC
## init(minResource:reductionFactor:minEarlyStoppingRate:bootstrapCount:trialFilter:)

### Description
Initializes an Asynchronous Successive Halving (ASHA) pruner.

### Signature
```swift
init(
    minResource: Int = 1,
    reductionFactor: Int = 4,
    minEarlyStoppingRate: Int = 0,
    bootstrapCount: Int = 0,
    trialFilter: (@Sendable (PersistedTrial) -> Bool)? = nil
)
```

### Parameters
- **minResource** (Int) - Optional - Minimum resource step before the first rung. Defaults to 1.
- **reductionFactor** (Int) - Optional - Promotion divisor η. Defaults to 4.
- **minEarlyStoppingRate** (Int) - Optional - Initial rung rate exponent. Defaults to 0.
- **bootstrapCount** (Int) - Optional - Trials needed at a rung before pruning begins. Defaults to 0.
- **trialFilter** ((@Sendable (PersistedTrial) -> Bool)?) - Optional - Optional closure to isolate trials by bracket.
```

--------------------------------

### Initialize and use TPESampler

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/tpesampler

Demonstrates creating a study with a seeded TPESampler and running an optimization trial.

```swift
let sampler = TPESampler(seed: 42)
let study = try Swiftuna.createStudy(sampler: sampler)
try study.optimize(nTrials: 100) { trial in
    let x = try trial.suggest("x", in: -10.0...10.0)
    return x * x
}
```

--------------------------------

### Retrieve Integer Value Example

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/persistedtrial/int%28_%3A%29

Demonstrates how to use the int(_:) method with a nil-coalescing operator to provide a default value.

```swift
let batchSize: Int = bestTrial.int("batch_size") ?? 32
```

--------------------------------

### Implement an ask-and-tell optimization loop

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/askandtellguide

Demonstrates the manual lifecycle of a trial, from parameter suggestion to result reporting. The trial is consumed upon calling tell, preventing accidental reuse.

```swift
var trial = try study.ask()
let lr = try trial.suggest("lr", in: 1e-4...1e-1)
let loss = trainModel(lr: lr)


// trial is consumed here; subsequent lines cannot touch it
try study.tell(consuming: trial, value: loss)
```

--------------------------------

### Initialize SQLite StorageBackend

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/storagebackend/sqlite%28url%3A%29

Creates a SQLite storage backend instance from a specified file URL.

```swift
static func sqlite(url: URL) -> StorageBackend
```

--------------------------------

### Initialize Journal Storage Backend

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/storagebackend/journal%28url%3A%29

Creates a Journal storage backend using a provided file URL.

```swift
static func journal(url: URL) -> StorageBackend
```

--------------------------------

### init(minResource:maxResource:reductionFactor:bootstrapCount:)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/hyperbandpruner/init%28minresource%3Amaxresource%3Areductionfactor%3Abootstrapcount%3A%29

Initializes a new instance of the HyperbandPruner with specified resource constraints and scaling factors.

```APIDOC
## init(minResource:maxResource:reductionFactor:bootstrapCount:)

### Description
Initializes a Hyperband pruner with configurable resource limits and scaling factors.

### Signature
`init(minResource: Int = 1, maxResource: Int = 80, reductionFactor: Int = 3, bootstrapCount: Int = 0)`

### Parameters
- **minResource** (Int) - Optional - Minimum resource step. Defaults to 1.
- **maxResource** (Int) - Optional - Maximum resource step. Defaults to 80.
- **reductionFactor** (Int) - Optional - Resource scaling factor (η). Defaults to 3.
- **bootstrapCount** (Int) - Optional - Trials required before pruning. Defaults to 0.
```

--------------------------------

### Instance Subscript Definition

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/trial/subscript%28userattr%3A%29

Defines the signature for the subscript(userAttr:) instance method with mutating get and set accessors.

```swift
subscript(userAttr key: String) -> String? { mutating get set }
```

--------------------------------

### init(_:)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/constraintkey/init%28_%3A%29

Initializes a new ConstraintKey with the provided name.

```APIDOC
## init(_:)

### Description
Initializes a new instance of `ConstraintKey` with a given name.

### Signature
`init(_ name: String)`

### Parameters
- **name** (String) - The name identifier for the constraint key.
```

--------------------------------

### init(categorical:)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/gridsampler/valuelist/init%28categorical%3A%29

Initializes a new ValueList instance using an array of categorical strings to define the parameter grid domain.

```APIDOC
## init(categorical:)

### Description
Creates a parameter grid domain from an array of categorical `String` choices.

### Signature
`init(categorical: [String])`

### Parameters
- **categorical** ([String]) - Required - An array of strings representing the categorical choices for the parameter grid.
```

--------------------------------

### Define subscript(_:) signature

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/study/subscript%28_%3A%29-7x0s5

Defines a subscript that accepts a String key and returns an optional String, supporting both get and set operations.

```swift
subscript(key: String) -> String? { get set }
```

--------------------------------

### init(lower:upper:)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/thresholdpruner/init%28lower%3Aupper%3A%29

Initializes a Threshold pruner with optional lower and upper bound cutoffs.

```APIDOC
## init(lower:upper:)

### Description
Initializes a Threshold pruner instance.

### Signature
`init(lower: Double? = nil, upper: Double? = nil)`

### Parameters
- **lower** (Double?) - Optional - Lower bound cutoff.
- **upper** (Double?) - Optional - Upper bound cutoff.
```

--------------------------------

### init()

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/nooptelemetrytracer/init%28%29

Initializes a new instance of the NoOpTelemetryTracer.

```APIDOC
## init()

### Description
Initializes a new instance of the NoOpTelemetryTracer class.

### Signature
`init()`
```

--------------------------------

### subscript(_:) Method Signature

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/trial/subscript%28_%3A%29-7ydma

Defines a subscript that accepts a constraint key type and returns an optional Double, supporting both get and set operations.

```swift
subscript<K>(key: K.Type) -> Double? where K : ConstraintKeyProtocol { mutating get set }
```

--------------------------------

### init(_:)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/attributekey/init%28_%3A%29

Initializes a new AttributeKey with the provided name.

```APIDOC
## init(_:)

### Description
Creates a new instance of an AttributeKey with the specified name.

### Signature
`init(_ name: String)`

### Parameters
- **name** (String) - The name used to identify the attribute key.
```

--------------------------------

### Swiftuna Optimization Loop

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna

Demonstrates creating a study, running an optimization loop with parameter suggestions, and inspecting the best trial results.

```swift
import Swiftuna


// 1. Create a study
let study = try Swiftuna.createStudy(
    name: "quickstart_study",
    direction: .minimize
)


// 2. Run the optimization loop
try study.optimize(nTrials: 100) { trial in
    let x = try trial.suggest("x", in: -10.0...10.0)
    let y = try trial.suggest("y", in: 0...5)
    return (x - 2.0) * (x - 2.0) + Double(y)
}


// 3. Inspect results
if let best = try study.bestTrial {
    print("Optimal trial #\(best.number): value = \(best.value ?? 0.0)")
    print("Parameters: \(best.params)")
}
```

--------------------------------

### subscript<V>(key: AttributeKey<V>)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/trial/subscript%28_%3A%29-6suzl

Accesses or modifies a value associated with the specified AttributeKey. This subscript supports both getting and setting values that conform to AttributeConvertible.

```APIDOC
## subscript(_:)

### Description
Accesses or modifies a value associated with the specified AttributeKey. This subscript supports both getting and setting values that conform to AttributeConvertible.

### Signature
`subscript<V>(key: AttributeKey<V>) -> V? where V : AttributeConvertible { mutating get set }`

### Parameters
- **key** (AttributeKey<V>) - Required - The key used to identify the attribute value.

### Returns
- **V?** - The value associated with the key, or nil if the key does not exist.
```

--------------------------------

### StorageBackend.journal(path:)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/storagebackend/journal%28path%3A%29

Initializes a journal storage backend at the specified file system path.

```APIDOC
## StorageBackend.journal(path:)

### Description
Initializes a high-throughput, lockless, append-only journal storage backend. This is recommended for distributed environments, NFS network filesystems, or scenarios with thousands of concurrent workers to avoid SQLite write-lock contention.

### Signature
`case journal(path: String)`

### Parameters
- **path** (String) - Required - The file system path where the journal storage will be maintained.
```

--------------------------------

### Manual Ask-and-Tell Optimization Loop

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/study/ask%28%29

Demonstrates the manual workflow of asking for a trial, suggesting parameters, evaluating, and reporting the result back to the study.

```swift
var trial = try study.ask()
let x = try trial.suggest("x", in: -10.0...10.0)
let loss = evaluate(x)
try study.tell(consuming: trial, value: loss)
```

--------------------------------

### Initialize NSGAIISampler

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/samplersandpruners

Configures the genetic algorithm sampler for multi-objective optimization tasks.

```swift
let sampler = NSGAIISampler(
    populationSize: 50,
    crossoverProb: 0.9,
    swappingProb: 0.5,
    seed: 42
)
```

--------------------------------

### init(rawValue:)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/trialstate/init%28rawvalue%3A%29

Initializes a new TrialState instance from the provided raw integer value.

```APIDOC
## init(rawValue:)

### Description
Creates a new instance of TrialState from a given raw Int32 value. This is inherited from the RawRepresentable protocol.

### Signature
`init?(rawValue: Int32)`

### Parameters
- **rawValue** (Int32) - The raw integer value used to initialize the TrialState instance.
```

--------------------------------

### static func sqlite(url: URL) -> StorageBackend

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/storagebackend/sqlite%28url%3A%29

Initializes a new SQLite storage backend using the provided file URL.

```APIDOC
## static func sqlite(url: URL) -> StorageBackend

### Description
Creates a SQLite storage backend from a `Foundation.URL`.

### Parameters
- **url** (URL) - Required - File URL pointing to the SQLite database file.

### Return Value
- **StorageBackend** - An instance of the storage backend configured for the specified SQLite file.
```

--------------------------------

### init(number:state:value:values:params:internalParams:userAttrs:constraints:intermediateValues:datetimeStart:datetimeComplete:)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/persistedtrial/init%28number%3Astate%3Avalue%3Avalues%3Aparams%3Ainternalparams%3Auserattrs%3Aconstraints%3Aintermediatevalues%3Adatetimestart%3Adatetimecomplete%3A%29

Initializes a new PersistedTrial instance with the provided trial data and configuration parameters.

```APIDOC
## init(number:state:value:values:params:internalParams:userAttrs:constraints:intermediateValues:datetimeStart:datetimeComplete:)

### Description
Creates a persisted trial record with strongly-typed parameter values.

### Signature
```swift
init(
    number: Int,
    state: TrialState,
    value: Double?,
    values: [Double] = [],
    params: [String : ParameterValue],
    internalParams: [String : Double] = [:],
    userAttrs: [String : String] = [:],
    constraints: [String : Double] = [:],
    intermediateValues: [Int : Double] = [:],
    datetimeStart: Date? = nil,
    datetimeComplete: Date? = nil
)
```
```

--------------------------------

### Initialize QMCSampler

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/qmcsampler/init%28seed%3A%29

Creates a new instance of the QMC Sobol sequence sampler.

```swift
init(seed: UInt64? = nil)
```

--------------------------------

### MedianPruner(nStartupTrials:nWarmupSteps:intervalSteps:)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/medianpruner

Initializes a new instance of the MedianPruner.

```APIDOC
## init(nStartupTrials: Int, nWarmupSteps: Int, intervalSteps: Int)

### Description
Initializes a Median pruner with specified startup trials, warmup steps, and evaluation interval.

### Parameters
- **nStartupTrials** (Int) - Number of initial trials executed without pruning to establish an initial performance baseline.
- **nWarmupSteps** (Int) - Number of initial steps within each trial before pruning evaluation begins.
- **intervalSteps** (Int) - Step interval at which pruning decisions are evaluated.
```

--------------------------------

### init(number:state:value:values:params:userAttrs:constraints:intermediateValues:datetimeStart:datetimeComplete:)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/persistedtrial/init%28number%3Astate%3Avalue%3Avalues%3Aparams%3Auserattrs%3Aconstraints%3Aintermediatevalues%3Adatetimestart%3Adatetimecomplete%3A%29

A backwards-compatible convenience initializer for creating a PersistedTrial instance.

```APIDOC
## init(number:state:value:values:params:userAttrs:constraints:intermediateValues:datetimeStart:datetimeComplete:)

### Description
Initializes a new PersistedTrial instance using a set of numerical parameters, state, and optional metadata.

### Signature
```swift
init(
    number: Int,
    state: TrialState,
    value: Double?,
    values: [Double] = [],
    params: [String : Double],
    userAttrs: [String : String] = [:],
    constraints: [String : Double] = [:],
    intermediateValues: [Int : Double] = [:],
    datetimeStart: Date? = nil,
    datetimeComplete: Date? = nil
)
```
```

--------------------------------

### Creating a Study with Hyperband Pruning

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/createstudy%28name%3Adirection%3Astorage%3Asampler%3Apruner%3Aloadifexists%3A%29

Initializes a study using SQLite storage, TPE sampling, and Hyperband pruning.

```swift
let study = try Swiftuna.createStudy(
    name: "hyperband_tuning",
    direction: .minimize,
    storage: .sqlite(path: "experiments.db"),
    sampler: TPESampler(),
    pruner: HyperbandPruner(),
    loadIfExists: true
)
```

--------------------------------

### init(_ elements: [Int])

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/gridsampler/valuelist/init%28_%3A%29-3sexv

Initializes a new instance of ValueList using an array of integers.

```APIDOC
## init(_:)

### Description
Creates a parameter grid domain from an array of `Int` values.

### Signature
`init(_ elements: [Int])`

### Parameters
- **elements** ([Int]) - Required - An array of integers used to define the parameter grid domain.
```

--------------------------------

### init(seed:)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/tpesampler/init%28seed%3A%29

Initializes a TPE sampler with an optional seed for random number generation.

```APIDOC
## init(seed:)

### Description
Initializes a TPE sampler. If a seed is provided, it is used for random number generation; otherwise, a random seed is selected.

### Signature
`init(seed: UInt64? = nil)`

### Parameters
- **seed** (UInt64?) - Optional - Seed for random number generation. If nil, a random seed is selected.
```

--------------------------------

### init(stringLiteral:)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/constraintkey/init%28stringliteral%3A%29

Initializes a new ConstraintKey instance using a string literal value.

```APIDOC
## init(stringLiteral:)

### Description
Initializes a ConstraintKey from a string literal. This method is inherited from ExpressibleByStringLiteral.

### Signature
`init(stringLiteral value: String)`

### Parameters
- **value** (String) - The string literal used to initialize the ConstraintKey.
```

--------------------------------

### init(seed:)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/randomsampler/init%28seed%3A%29

Initializes a random sampler with an optional seed for reproducibility.

```APIDOC
## init(seed:)

### Description
Initializes a random sampler. If a seed is provided, the sampler will produce reproducible results; otherwise, a non-deterministic seed is used.

### Signature
`init(seed: UInt64? = nil)`

### Parameters
- **seed** (UInt64?) - Optional - A seed value for reproducibility. If set to nil, a non-deterministic seed is selected.
```

--------------------------------

### Initialize MedianPruner

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/medianpruner/init%28nstartuptrials%3Anwarmupsteps%3Aintervalsteps%3A%29

Initializes a Median pruner with configurable parameters for trial startup, warmup, and evaluation intervals.

```swift
init(
    nStartupTrials: Int = 5,
    nWarmupSteps: Int = 0,
    intervalSteps: Int = 1
)
```

--------------------------------

### init(searchSpace:seed:)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/gridsampler

Initializes a new GridSampler instance with a defined search space and an optional seed for deterministic shuffling.

```APIDOC
## init(searchSpace: [String : GridSampler.ValueList], seed: UInt64?)

### Description
Initializes a GridSampler with typed GridSampler.ValueList domains.

### Parameters
- **searchSpace** ([String : GridSampler.ValueList]) - Required - The dictionary defining the parameter domains.
- **seed** (UInt64?) - Optional - A seed for deterministic shuffling of the grid evaluation sequence.
```

--------------------------------

### init(from:)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/parametervalue/init%28from%3A%29

Initializes a new ParameterValue instance from the provided decoder.

```APIDOC
## init(from:)

### Description
Creates a new instance of ParameterValue by decoding from the given decoder. This method is inherited from the Decodable protocol.

### Signature
`init(from decoder: any Decoder) throws`

### Parameters
- **decoder** (any Decoder) - The decoder to read data from.

### Throws
- Throws an error if the data is invalid or cannot be decoded.
```

--------------------------------

### init(from:)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/trialstate/init%28from%3A%29

Initializes a new instance of TrialState by decoding from the provided decoder. This method is available when the type conforms to Decodable and its RawValue is Int32.

```APIDOC
## init(from:)

### Description
Initializes a new instance of TrialState by decoding from the provided decoder. This method is inherited from RawRepresentable and is available when the type conforms to Decodable and its RawValue is Int32.

### Signature
`init(from decoder: any Decoder) throws`

### Parameters
- **decoder** (any Decoder) - The decoder to read data from.
```

--------------------------------

### init(wrappedPruner:patience:minDelta:)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/patientpruner/init%28wrappedpruner%3Apatience%3Amindelta%3A%29

Initializes a new instance of PatientPruner with optional base pruner, patience count, and minimum delta threshold.

```APIDOC
## init(wrappedPruner:patience:minDelta:)

### Description
Initializes a Patient pruner. This allows for wrapping an existing pruner to add patience-based pruning logic.

### Signature
```swift
init(
    wrappedPruner: (any Pruner)? = nil,
    patience: Int,
    minDelta: Double = 0.0
)
```

### Parameters
- **wrappedPruner** ((any Pruner)?) - Optional - Optional base pruner to wrap with patience.
- **patience** (Int) - Required - Consecutive steps tolerated before pruning triggers.
- **minDelta** (Double) - Optional - Minimum improvement threshold for standalone mode. Defaults to 0.0.
```

--------------------------------

### init(_:)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/codableattribute/init%28_%3A%29

Initializes a new CodableAttribute instance by wrapping a provided Codable value.

```APIDOC
## init(_:)

### Description
Wraps a Codable value for attribute storage.

### Signature
`init(_ value: T)`
```

--------------------------------

### Create an in-memory study

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/gettingstarted

Initialize a study object to manage trials and track optimization results in memory.

```swift
import Swiftuna


// Create an in-memory study for single-objective minimization
let study = try Swiftuna.createStudy(
    name: "learning_rate_search",
    direction: .minimize,
    storage: .inMemory
)
```

--------------------------------

### Initialize PercentilePruner

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/percentilepruner/init%28percentile%3Anstartuptrials%3Anwarmupsteps%3Aintervalsteps%3A%29

Defines the configuration parameters for the PercentilePruner instance.

```swift
init(
    percentile: Double = 50.0,
    nStartupTrials: Int = 5,
    nWarmupSteps: Int = 0,
    intervalSteps: Int = 1
)
```

--------------------------------

### createStudy(name:directions:storage:sampler:pruner:loadIfExists:)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/createstudy%28name%3Adirections%3Astorage%3Asampler%3Apruner%3Aloadifexists%3A%29

Creates a multi-objective study with custom sampler and optional pruner.

```APIDOC
## func createStudy<S>(name:directions:storage:sampler:pruner:loadIfExists:)

### Description
Creates a multi-objective study with custom sampler and optional pruner.

### Signature
```swift
func createStudy<S>(
    name: String = "default",
    directions: [Direction],
    storage: StorageBackend = .inMemory,
    sampler: S,
    pruner: any Pruner = NopPruner(),
    loadIfExists: Bool = false
) throws(SwiftunaError) -> Study where S : Sampler
```

### Parameters
- **name** (String) - Optional - The name of the study, defaults to "default".
- **directions** ([Direction]) - Required - The optimization directions for the study.
- **storage** (StorageBackend) - Optional - The storage backend to use, defaults to .inMemory.
- **sampler** (S) - Required - The sampler instance to use for the study.
- **pruner** (any Pruner) - Optional - The pruner instance to use, defaults to NopPruner().
- **loadIfExists** (Bool) - Optional - Whether to load the study if it already exists, defaults to false.

### Returns
- **Study** - The created or loaded study instance.

### Throws
- **SwiftunaError** - Thrown if the study creation or loading fails.
```

--------------------------------

### createStudy(name:directions:storage:pruner:loadIfExists:)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/createstudy%28name%3Adirections%3Astorage%3Apruner%3Aloadifexists%3A%29

Creates a multi-objective study with default NSGAIISampler (if directions.count > 1) or TPESampler.

```APIDOC
## createStudy(name:directions:storage:pruner:loadIfExists:)

### Description
Creates a multi-objective study with default NSGAIISampler (if directions.count > 1) or TPESampler.

### Signature
```swift
func createStudy(
    name: String = "default",
    directions: [Direction],
    storage: StorageBackend = .inMemory,
    pruner: any Pruner = NopPruner(),
    loadIfExists: Bool = false
) throws(SwiftunaError) -> Study
```

### Parameters
- **name** (String) - Optional - The name of the study, defaults to "default".
- **directions** ([Direction]) - Required - The optimization directions for the study.
- **storage** (StorageBackend) - Optional - The storage backend to use, defaults to .inMemory.
- **pruner** (any Pruner) - Optional - The pruner to use, defaults to NopPruner().
- **loadIfExists** (Bool) - Optional - Whether to load the study if it already exists, defaults to false.

### Returns
- **Study** - The created or loaded study instance.

### Throws
- **SwiftunaError** - Thrown if the study creation fails.
```

--------------------------------

### init(seed: UInt64?)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/tpesampler

Initializes a new instance of the TPESampler with an optional seed for the pseudorandom number generator.

```APIDOC
## init(seed: UInt64?)

### Description
Initializes a TPE sampler. If a seed is provided, it ensures deterministic behavior; otherwise, a non-deterministic seed is generated.

### Parameters
- **seed** (UInt64?) - Optional - The seed for the pseudorandom number generator.
```

--------------------------------

### Initialize and use GridSampler

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/gridsampler

Defines a search space using GridSampler.ValueList and executes an optimization study.

```swift
let searchSpace: [String: GridSampler.ValueList] = [
    "learning_rate": [0.001, 0.01, 0.1],
    "batch_size": [16, 32, 64],
    "optimizer": .init(categorical: ["adam", "sgd"])
]


let sampler = GridSampler(searchSpace: searchSpace, seed: 123)
let study = try Swiftuna.createStudy(sampler: sampler)
try study.optimize(nTrials: 18) { trial in
    let lr = try trial.suggest("learning_rate", in: 0.001...0.1)
    let batch = try trial.suggest("batch_size", in: 16...64)
    let opt = try trial.suggest("optimizer", from: ["adam", "sgd"])
    return trainModel(lr: lr, batch: batch, opt: opt)
}
```

--------------------------------

### Initialize a StudySummary record

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/studysummary/init%28id%3Aname%3Adirections%3Auserattrs%3Asystemattrs%3Atrialcount%3A%29

Use this initializer to create a new study summary instance with required ID, name, and directions, along with optional attributes and trial counts.

```swift
init(
    id: Int,
    name: String,
    directions: [Direction],
    userAttrs: [String : String] = [:],
    systemAttrs: [String : String] = [:],
    trialCount: Int = 0
)
```

--------------------------------

### Initialize ValueList with categorical choices

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/gridsampler/valuelist/init%28categorical%3A%29

Creates a parameter grid domain using an array of categorical String values.

```swift
init(categorical: [String])
```

--------------------------------

### init(stringLiteral:)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/parametervalue/init%28stringliteral%3A%29

Initializes a new ParameterValue instance using a string literal.

```APIDOC
## init(stringLiteral:)

### Description
Initializes a ParameterValue instance from a string literal. This method is inherited from ExpressibleByStringLiteral.

### Signature
`init(stringLiteral value: String)`

### Parameters
- **value** (String) - The string literal value to initialize the ParameterValue.
```

--------------------------------

### init(unicodeScalarLiteral:)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/constraintkey/init%28unicodescalarliteral%3A%29

Initializes a ConstraintKey instance using a Unicode scalar literal value.

```APIDOC
## init(unicodeScalarLiteral:)

### Description
Initializes a ConstraintKey instance from a Unicode scalar literal. This is inherited from ExpressibleByExtendedGraphemeClusterLiteral and is available when ExtendedGraphemeClusterLiteralType is Self.UnicodeScalarLiteralType.

### Signature
`init(unicodeScalarLiteral value: Self.ExtendedGraphemeClusterLiteralType)`

### Parameters
- **value** (Self.ExtendedGraphemeClusterLiteralType) - The Unicode scalar literal value used to initialize the instance.
```

--------------------------------

### init(_ elements: [Double])

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/gridsampler/valuelist/init%28_%3A%29-1p0no

Initializes a new ValueList instance from an array of Double values.

```APIDOC
## init(_ elements: [Double])

### Description
Creates a parameter grid domain from an array of `Double` values.

### Signature
`init(_ elements: [Double])`

### Parameters
- **elements** ([Double]) - Required - An array of double-precision floating-point values used to define the parameter grid domain.
```

--------------------------------

### init(arrayLiteral:)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/gridsampler/valuelist/init%28arrayliteral%3A%29

Initializes a new ValueList instance from a floating-point array literal.

```APIDOC
## init(arrayLiteral:)

### Description
Creates a parameter grid domain from a floating-point array literal.

### Signature
`init(arrayLiteral elements: Double...)`

### Parameters
- **elements** (Double...) - Required - A variadic list of floating-point numbers used to populate the value list.
```

--------------------------------

### func ask() -> Trial

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/study

Creates a new trial from which hyperparameters can be suggested.

```APIDOC
## func ask()

### Description
Creates a new trial from which hyperparameters can be suggested.

### Signature
`func ask() throws(SwiftunaError) -> Trial`
```

--------------------------------

### Initialize PercentilePruner

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/percentilepruner

Creates a pruner instance that retains trials in the top 25% after a startup period of 5 trials.

```swift
// Keep only trials performing in the top 25% (prune bottom 75%)
let pruner = PercentilePruner(percentile: 25.0, nStartupTrials: 5)
```

--------------------------------

### init(integerLiteral:)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/parametervalue/init%28integerliteral%3A%29

Initializes a new ParameterValue instance using an integer literal.

```APIDOC
## init(integerLiteral:)

### Description
Initializes a ParameterValue instance from an integer literal. This method is inherited from the ExpressibleByIntegerLiteral protocol.

### Signature
`init(integerLiteral value: Int)`

### Parameters
- **value** (Int) - The integer value to initialize the ParameterValue with.
```

--------------------------------

### init(rawValue:)

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/direction/init%28rawvalue%3A%29

Initializes a new Direction instance from a raw Int32 value.

```APIDOC
## init(rawValue:)

### Description
Initializes a new Direction instance from a raw Int32 value. This initializer is inherited from the RawRepresentable protocol.

### Signature
`init?(rawValue: Int32)`

### Parameters
- **rawValue** (Int32) - The raw integer value used to initialize the Direction instance.
```

--------------------------------

### Execute batch suggestions for GPU parallelism

Source: https://zuidvolt.github.io/swiftuna/documentation/swiftuna/askandtellguide

Collects multiple trials to evaluate in parallel, optimizing hardware utilization for GPU-bound tasks.

```swift
let study = try Swiftuna.createStudy(name: "batch_eval", direction: .minimize)


let batchSize = 8
var activeBatch: [Trial] = []


// 1. Collect a batch of candidate configurations
for _ in 0..<batchSize {
    activeBatch.append(try study.ask())
}


// 2. Suggest parameters for each trial in the batch
var configs: [(lr: Double, wd: Double)] = []
for i in 0..<activeBatch.count {
    let lr = try activeBatch[i].suggest("lr", in: 1e-4...1e-1, log: true)
    let wd = try activeBatch[i].suggest("wd", in: 1e-6...1e-2, log: true)
    configs.append((lr: lr, wd: wd))
}


// 3. Run parallel GPU batch evaluation
let losses = await evaluateBatchOnGPU(configs)


// 4. Report all results back
for (trial, loss) in zip(activeBatch, losses) {
    try study.tell(consuming: trial, value: loss)
}
```
Tokens:
Raw