Python API

The public Python modules are documented below. The docstrings include usage examples for the common construction paths.

Python entry point for FuncCraft.

Importing funccraft gives you both the plain-data specification types and the runtime benchmark wrappers:

• spec types and make_* helpers live in funccraft.spec;

• one-function runtime wrappers live in funccraft.benchmark_function;

• suite-level runtime wrappers live in funccraft.suite.

Examples

Use the built-in suite collection:

import funccraft as fc

year = 2026
version = 1
collection = fc.suite_collection(year, version)
suite = collection.benchmark_suite(dimension=10)
values = suite.evaluate(0, [[0.0] * 10])

Create one function manually:

import funccraft as fc

spec = fc.make_function_spec(
    dimension=2,
    domain=fc.make_domain(2, -10.0, 10.0),
    components=[fc.make_component(base_function="Ackley")],
    assigned_xopt=[0.0, 0.0],
    scale_factor=1.0,
)
f = fc.BenchmarkFunction(spec)
y = f([[0.0, 0.0]])

Python helpers for FuncCraft specs.

The C++ bindings expose the actual plain-data spec structs. This module adds readable make_* factory functions and dict-to-spec conversion so Python users can construct FuncCraft functions without knowing the C++ headers.

Terminology

DomainSpec

Search bounds in the generated coordinates.

CoordinateTransformSpec

Moves from generated/search coordinates into the component’s primitive coordinates. input_dimension is the parent/search dimension, output_dimension is the component dimension after transformation, and assigned_xopt is output-dimensional. The primitive optimum target is resolved internally from the selected base function and domain scaling.

ValueTransformSpec

Optional value-shape transform applied to a component output.

ComponentSpec

One component in a function. A component is either a basic function such as "Rastrigin" or a nested composed function via composed_function.

CompositionSpec

Combines component values. "none" is the identity/single-component case, "cpm-..." choices are continuous composition methods, and "dpm-..." choices are deceptive composition methods. DPM centers and biases live on the composition spec because they define deceptive local traps.

FunctionSpec

Complete description of one benchmark function, including assigned global optimum location/value and scale factor.

SuiteSpec

Sampling rules for generating many distinct function specs.

Examples

Create a single 2D function and evaluate it through BenchmarkFunction:

from funccraft import (
    BenchmarkFunction,
    make_component,
    make_coordinate_transform,
    make_domain,
    make_function_spec,
)

spec = make_function_spec(
    dimension=2,
    domain=make_domain(2, -10.0, 10.0),
    components=[
        make_component(
            base_function="Sphere",
            coordinate_transform=make_coordinate_transform(
                "rotation",
                assigned_xopt=[1.0, -1.0],
                seed=1,
            ),
        ),
    ],
    assigned_xopt=[1.0, -1.0],
    assigned_fopt=0.0,
    scale_factor=1.0,
    seed=10,
)
f = BenchmarkFunction(spec)
y = f([[1.0, -1.0], [0.0, 0.0]])

Create a small deceptive composition from two base functions:

spec = make_function_spec(
    dimension=2,
    domain=make_domain(2, -10.0, 10.0),
    components=[
        make_component(base_function="Rastrigin"),
        make_component(base_function="Ackley"),
    ],
    composition=make_composition(
        "dpm-softmax",
        parameters=[0.01],
        biases=[0.0, 20.0],
    ),
    assigned_xopt=[2.0, -3.0],
    scale_factor=1.0,
    seed=11,
)

Create a suite spec. Choice probabilities in each choice table are fractions and should sum to one:

suite_spec = make_suite_spec(
    requested_number_of_functions=500,
    max_components=4,
    master_seed=1,
    compositions=[
        make_composition_choice("cpm-wsum", 0.25),
        make_composition_choice("cpm-power-mean", 0.25),
        make_composition_choice("dpm-softmax", 0.25, [0.01]),
        make_composition_choice("dpm-bgsoftmax", 0.25, [0.01, 1.0, 0.01]),
    ],
)

funccraft.spec.basic_function_id(value)

funccraft.spec.component_spec(data)

funccraft.spec.composition_choice(data)

funccraft.spec.composition_kind(value)

funccraft.spec.composition_spec(data)

funccraft.spec.coordinate_transform_choice(data)

funccraft.spec.coordinate_transform_kind(value)

funccraft.spec.coordinate_transform_spec(data)

funccraft.spec.domain_spec(data)

funccraft.spec.function_spec(data)

funccraft.spec.make_choice(kind, probability=1.0, parameters=None)

Alias for make_composition_choice.

Use the explicit make_coordinate_transform_choice or make_value_transform_choice when constructing those choice tables.

funccraft.spec.make_component(base_function=None, composed_function=None, coordinate_transform=None, value_transform=None, seed=0)

Create a native ComponentSpec.

base_function accepts a BasicFunctionId, integer id, or name. It is required only when composed_function is not set. A composed component may be a FunctionSpec, compatible dict, or object exposing a spec attribute such as BenchmarkFunction. coordinate_transform and value_transform may be native specs or dictionaries with the same field names.

Examples

Basic-function component:

component = make_component(
    base_function="Rosenbrock",
    coordinate_transform=make_coordinate_transform("rotation", seed=5),
    value_transform=make_value_transform("none"),
)

Nested composed-function component:

child = make_function_spec(
    dimension=2,
    components=[make_component(base_function="Sphere")],
    assigned_xopt=[0.0, 0.0],
    scale_factor=1.0,
)
component = make_component(composed_function=child)

funccraft.spec.make_composition(kind='none', parameters=None, biases=None, centers=None)

Create a native CompositionSpec.

Parameters

kind:

"none" for a single identity component, "cpm-wsum", "cpm-power-mean", "cpm-level-well", "dpm-softmax", or "dpm-bgsoftmax".

parameters:

Composition-specific numeric parameters.

biases:

DPM-only component biases used to create deceptive local traps.

centers:

DPM-only full-dimensional component centers. Users normally omit this; exported materialized specs include resolved centers.

Examples

Identity/single-component composition:

composition = make_composition("none")

DPM composition with two component biases:

composition = make_composition(
    "dpm-softmax",
    parameters=[0.01],
    biases=[0.0, 25.0],
)

funccraft.spec.make_composition_choice(kind, probability=1.0, parameters=None)

Create a weighted composition choice for SuiteSpec.

Choice probabilities in the same table are interpreted as fractions and should sum to one.

funccraft.spec.make_coordinate_transform(kind='none', input_dimension=0, output_dimension=0, assigned_xopt=None, selected_indices=None, parameters=None, matrix=None, seed=0)

Create a native CoordinateTransformSpec.

assigned_xopt is the desired optimum location in the transform output coordinates. For full transforms this is the full generated/search point; for block rotation this is the selected subspace point. The transform target is determined internally from the selected base function and domain scaling.

Parameters

kind:

One of "none", "rotation", "affine", or "block-rotation". Names are normalized, so "Block Rotation", "block_rotation", and "block-rotation" are equivalent.

input_dimension:

Ambient/search dimension. Leave as 0 to let FuncCraft infer it from the parent function dimension.

output_dimension:

Component input dimension after transformation. Leave as 0 to let FuncCraft infer it from input_dimension or selected_indices.

assigned_xopt:

Desired component optimum in generated coordinates. If omitted, FuncCraft uses the function-level assigned optimum or a generated center, depending on the suite construction mode.

selected_indices:

Optional coordinate subset used by block rotation.

matrix:

Optional materialized transform matrix. Users normally omit this; exported materialized specs include it.

Examples

Full-dimensional rotation with generated matrix:

transform = make_coordinate_transform(
    "rotation",
    assigned_xopt=[1.0, -1.0],
    seed=123,
)

Block rotation on selected coordinates:

transform = make_coordinate_transform(
    "block-rotation",
    selected_indices=[0, 2, 4],
    seed=123,
)

funccraft.spec.make_coordinate_transform_choice(kind, probability=1.0, parameters=None)

Create a weighted coordinate-transform choice for SuiteSpec.

Choice probabilities in the same table are interpreted as fractions and should sum to one.

funccraft.spec.make_domain(dimension, lower_bound=-100.0, upper_bound=100.0)

Create a native DomainSpec.

lower_bound and upper_bound may be scalars or length-dimension sequences.

Examples

Uniform bounds:

domain = make_domain(10, -100.0, 100.0)

Per-coordinate bounds:

domain = make_domain(2, lower_bound=[-5.0, -1.0], upper_bound=[5.0, 1.0])

funccraft.spec.make_function_spec(dimension, domain=None, components=None, composition=None, assigned_xopt=None, assigned_fopt=0.0, scale_factor=None, seed=0, label='', metadata=None)

Create a native FunctionSpec.

components may contain native ComponentSpec objects or dictionaries. scale_factor=None lets FuncCraft choose the scale internally.

Important fields

assigned_xopt

Desired global minimizer in generated/search coordinates. If omitted, FuncCraft generates it from seed.

assigned_fopt

Desired objective value at the assigned global minimizer.

scale_factor

Multiplicative value scale. Use None for internal estimation, or a positive value when you want exact control.

seed

Function-level seed used for generated runtime details such as missing assigned optima and transform parameters.

Examples

A single shifted Sphere:

spec = make_function_spec(
    dimension=3,
    domain=make_domain(3, -5.0, 5.0),
    components=[make_component(base_function="Sphere")],
    assigned_xopt=[1.0, 2.0, 3.0],
    assigned_fopt=-100.0,
    scale_factor=1.0,
)

A composition with nested components can be built by passing a FunctionSpec to make_component(composed_function=...).

funccraft.spec.make_suite_spec(supported_dimensions=None, base_functions=None, composition_base_functions=None, coordinate_transforms=None, value_transforms=None, compositions=None, min_components=None, max_components=None, max_nested_composition_depth=None, nested_probability=None, requested_number_of_functions=None, max_number_of_functions=None, master_seed=None, lower_bound=None, upper_bound=None, assigned_fopt=None, xopt_domain_shrink_factor=None, suite_label=None)

Create a native SuiteSpec.

Omitted fields keep the C++ defaults. Choice tables accept native choice objects or dictionaries with kind, probability, and parameters. max_nested_composition_depth=0 means composed suite functions use only primitive components. Larger values allow composed functions as components; nested_probability controls how often each component is nested.

Examples

Generate 1,000 functions using default choices except for dimensions, component count, and nesting:

spec = make_suite_spec(
    supported_dimensions="2,5,10,20",
    requested_number_of_functions=1000,
    min_components=2,
    max_components=5,
    max_nested_composition_depth=2,
    nested_probability=0.25,
    master_seed=2026,
)

Replace the composition choice table explicitly. Probabilities should sum to one:

spec = make_suite_spec(
    requested_number_of_functions=200,
    compositions=[
        make_composition_choice("cpm-wsum", 0.4),
        make_composition_choice("cpm-level-well", 0.2),
        make_composition_choice("dpm-softmax", 0.4, [0.01]),
    ],
)

funccraft.spec.make_value_transform(kind='none', parameters=None)

Create a native ValueTransformSpec.

Examples

Use no value transform, or add an implemented value transform by name:

identity = make_value_transform("none")
warped = make_value_transform("oscillatory")

Names are normalized across case, spaces, hyphens, and underscores.

funccraft.spec.make_value_transform_choice(kind, probability=1.0, parameters=None)

Create a weighted value-transform choice for SuiteSpec.

Choice probabilities in the same table are interpreted as fractions and should sum to one.

funccraft.spec.spec_to_dict(spec)

Convert a native C++ spec/choice object to a plain Python dict.

funccraft.spec.suite_spec(data)

funccraft.spec.value_transform_choice(data)

funccraft.spec.value_transform_kind(value)

funccraft.spec.value_transform_spec(data)

Runtime benchmark-function wrapper for FuncCraft.

Use BenchmarkFunction when you already have a full FunctionSpec and want a callable object with the derived runtime pieces materialized. It is the high-level object for evaluating one concrete benchmark instance.

Examples

Build and evaluate one function. FuncCraft evaluation is batched, so pass a list of candidate vectors even when evaluating a single point:

from funccraft import (
    BenchmarkFunction,
    make_component,
    make_coordinate_transform,
    make_domain,
    make_function_spec,
)

spec = make_function_spec(
    dimension=2,
    domain=make_domain(2, -10.0, 10.0),
    components=[
        make_component(
            base_function="Rastrigin",
            coordinate_transform=make_coordinate_transform(
                "rotation",
                seed=123,
            ),
        ),
    ],
    assigned_xopt=[3.0, -2.0],
    assigned_fopt=10.0,
    scale_factor=1.0,
    seed=7,
)

f = BenchmarkFunction(spec)
values = f([[0.0, 0.0], [3.0, -2.0]])
f.export_spec("rastrigin_2d.yaml")

The exported YAML contains the materialized matrix, assigned optimum, scale factor, and other parameters needed to rebuild the same function later.

class funccraft.benchmark_function.BenchmarkFunction(spec)

Bases: object

Concrete benchmark function.

Parameters

spec:

A FunctionSpec, compatible dictionary, YAML path, native C++ BenchmarkFunction, or object convertible by funccraft.spec.function_spec().

Notes

This wrapper delegates all heavy lifting to the compiled extension. It is intentionally small, but the attribute names mirror the structure of the underlying spec so the object can be inspected without reading C++.

The callable interface is batched: f([[x0, x1]]) returns a list with one value. A bare vector such as f([x0, x1]) is intentionally not the public interface because suites and optimizers usually evaluate batches.

Examples

Construct from a dictionary instead of using the helper classes:

f = BenchmarkFunction({
    "dimension": 2,
    "domain": {"dimension": 2, "lower_bound": [-5, -5], "upper_bound": [5, 5]},
    "components": [
        {
            "base_function": "Sphere",
            "coordinate_transform": {
                "kind": "none",
                "assigned_xopt": [1.0, -1.0],
            },
            "value_transform": {"kind": "none"},
        },
    ],
    "composition": {"kind": "none"},
    "assigned_xopt": [1.0, -1.0],
    "assigned_fopt": 0.0,
    "scale_factor": 1.0,
})

print(f.dimension)
print(f.get_fopt())
print(f.get_xopt())
print(f([[1.0, -1.0], [0.0, 0.0]]))

__call__(points)

Evaluate a batch of candidate points.

Parameters

points:

A list of vectors, each with length equal to the function dimension.

Returns

list[float]

One objective value per input vector.

Examples

points is a list of points, not a single point:

values = f([[0.0] * f.dimension])

property component_types

Return a compact summary of immediate component source types.

Examples include "3 basic" or "2 basic, 1 level-1 nested".

property dimension

Return the ambient dimension of this function.

property domain

Return the search domain of this function.

evaluate(points)

Evaluate a batch of candidate points.

This is the named equivalent of f(points) and is useful when passing a method reference to optimizers.

export_spec(path)

Write the materialized function spec to a YAML file.

Examples

Archive and reload a materialized function:

before = f([[0.25, -0.5]])
f.export_spec("function.yaml")
g = BenchmarkFunction("function.yaml")
after = g([[0.25, -0.5]])
assert before == after

get_fopt()

Return the assigned optimum value.

get_xopt()

Return the assigned optimum location.

property scale

Alias for scale_factor.

property scale_factor

Return the runtime scale factor used to normalize values.

property spec

Return the normalized function specification used to build it.

funccraft.benchmark_function.load_function_spec(path)

Load a native FunctionSpec from a YAML file.

Examples

Load the spec first when you want to inspect or modify it before runtime construction:

spec = load_function_spec("rastrigin_2d.yaml")
print(spec.dimension, spec.assigned_xopt)
f = BenchmarkFunction(spec)

funccraft.benchmark_function.make_benchmark_function(spec)

Build a BenchmarkFunction from a spec object, dict, or file path.

This is a convenience alias for BenchmarkFunction(spec).

Examples

spec may be a native FunctionSpec, a compatible dictionary, a YAML path, or an already-created native C++ benchmark function:

f = make_benchmark_function("rastrigin_2d.yaml")
y = f([[0.0, 0.0]])

Runtime benchmark-suite wrapper for FuncCraft.

BenchmarkSuite is the object you use when you want a family of benchmark functions sampled from a SuiteSpec. It stores the generated blueprints lazily and materializes a concrete BenchmarkFunction only when you ask for a specific index.

Examples

Use the built-in 2026 v1 collection when you want the standard FuncCraft suite definition shipped with the package:

from funccraft import suite_collection

year = 2026
version = 1
collection = suite_collection(year, version)
print(collection.name, collection.number_of_functions)

suite = collection.benchmark_suite(dimension=10)
f0 = suite.function(0)
values = suite.evaluate(0, [[0.0] * suite.dimension])

Build a custom suite from Python specs when you want to control the sampling rules directly:

from funccraft import (
    BenchmarkSuite,
    make_composition_choice,
    make_suite_spec,
)

spec = make_suite_spec(
    requested_number_of_functions=100,
    max_components=4,
    master_seed=1,
    compositions=[
        make_composition_choice("cpm-wsum", 0.5),
        make_composition_choice("dpm-softmax", 0.5, [0.01]),
    ],
)
suite = BenchmarkSuite(spec, dimension=5)

class funccraft.suite.BenchmarkSuite(spec, dimension)

Bases: object

Concrete suite of generated benchmark functions.

Parameters

spec:

A SuiteSpec, compatible dictionary, or YAML path describing the sampling rules and default values.

dimension:

The fixed ambient dimension for every function in the suite.

Notes

The suite does not eagerly build every function. It keeps the generated blueprint list internally and materializes one function at a time.

All evaluation is batched. suite.evaluate(i, points) evaluates function index i on points, where points is a list of vectors.

Examples

Evaluate and export the generated suite manifest:

suite = BenchmarkSuite("suites/2026_v1.yaml", dimension=10)
f10 = suite.function(10)
y = suite(10, [[0.0] * 10, list(f10.spec.assigned_xopt)])
suite.export_manifest("suite_10d_manifest.yaml")

__call__(index, points)

Alias for evaluate().

property dimension

Return the fixed ambient dimension of the suite.

evaluate(index, points)

Evaluate one generated function on a batch of candidate points.

Parameters

index:

Zero-based function index.

points:

List of vectors with length equal to suite.dimension.

export_manifest(path)

Write the suite spec and all generated function specs to a YAML file.

The manifest is a materialized record of the generated suite: it contains the suite-level spec and every generated function spec.

export_spec(path)

Alias for export_manifest().

classmethod from_cpp(native)

Wrap an already-built native benchmark suite.

function(index)

Materialize one generated function by index.

This returns a Python BenchmarkFunction wrapper built from the function’s normalized spec.

Examples

BenchmarkFunction exposes the materialized single-function spec:

f = suite.function(42)
print(f.spec.label)
print(f.get_xopt())

property max_number_of_functions

Return the number of lazily generatable functions.

property size

Return the number of generated functions currently available.

property spec

Return the normalized suite specification.

property theoretical_max_number_of_functions

Return the combinatorial upper bound implied by the spec.

class funccraft.suite.SuiteCollection(year, version)

Bases: object

Built-in, versioned benchmark-suite collection.

A collection is a named suite definition stored in the package suites directory, for example 2026_v1.yaml. The YAML controls how many functions are in the collection; you choose the dimension when building a runtime BenchmarkSuite.

Examples

Create the standard 2026 v1 suite at two dimensions:

year = 2026
version = 1
collection = SuiteCollection(year, version)
print(collection.name)
print(collection.number_of_functions)

suite_2d = collection.benchmark_suite(2)
suite_10d = collection.benchmark_suite(10)
y = suite_10d.evaluate(0, [[0.0] * 10])

Get the underlying suite spec when you want to inspect the YAML-derived defaults before constructing a runtime suite:

spec = collection.spec()
print(spec.max_components, spec.master_seed)

benchmark_suite(dimension)

Build a runtime BenchmarkSuite at dimension.

property name

Human-readable collection name from the YAML file.

property number_of_functions

Number of functions defined by the collection YAML.

spec()

Return the native SuiteSpec for this collection.

property version

Collection version within the year, for example 1.

property year

Collection year, for example 2026.

funccraft.suite.list_suite_collections()

Return the built-in suite collections available in this package.

Examples

Each item identifies a versioned collection such as 2026 v1:

for item in list_suite_collections():
    print(item.year, item.version, item.name)

funccraft.suite.load_suite_spec(path)

Load a native SuiteSpec from a YAML file.

Examples

Load a suite definition, inspect it, then build a runtime suite:

spec = load_suite_spec("suites/2026_v1.yaml")
print(spec.requested_number_of_functions)
suite = BenchmarkSuite(spec, dimension=10)

funccraft.suite.make_benchmark_suite(spec, dimension)

Build a BenchmarkSuite for the requested dimension.

Examples

spec may be a native SuiteSpec, compatible dictionary, or YAML path:

suite = make_benchmark_suite("default_suite.yaml", dimension=10)
y = suite.evaluate(0, [[0.0] * suite.dimension])

funccraft.suite.suite_collection(year, version)

Return a SuiteCollection wrapper for a built-in collection.

Examples

Build a standard suite at any supported dimension:

year = 2026
version = 1
collection = suite_collection(year, version)
suite_2d = collection.benchmark_suite(2)
suite_20d = collection.benchmark_suite(20)

funccraft.suite.suite_collection_benchmark_suite(year, version, dimension)

Build a BenchmarkSuite from a built-in suite collection.

This is the functional shortcut for suite_collection(year, version).benchmark_suite(dimension).

funccraft.suite.suite_collection_number_of_functions(year, version)

Return the default function count for a built-in collection.

funccraft.suite.suite_collection_spec(year, version)

Return the native SuiteSpec for a built-in collection.