### CategoricalHyperparameter Initialization Example

Source: https://github.com/automl/configspace/blob/main/docs/reference/hyperparameters.md

Illustrates the initialization of a CategoricalHyperparameter, showing the use of UniformIntegerDistribution for the vectorized space and TransformerSeq for mapping to categorical choices.

```python
class CategoricalHyperparameter(Hyperparameter):
    def __init__(...):

        # ...
        super().__init__(
            vector_dist=UniformIntegerDistribution(size=len(choices)),
            transformer=TransformerSeq(seq=choices),
            ...
        )
```

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

### Install ConfigSpace

Source: https://github.com/automl/configspace/blob/main/docs/index.md

Provides the command to install the ConfigSpace package using pip. Requires Python 3.9 or higher.

```bash
pip install ConfigSpace
```

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

### Add Conditions to Configuration Space

Source: https://github.com/automl/configspace/blob/main/docs/guide.md

Adds the previously defined conditions (`cond_1`, `cond_2`, `cond_3`) to the `ConfigurationSpace` object. This finalizes the setup of conditional hyperparameters and prints the updated configuration space.

```python
cs.add([cond_1, cond_2, cond_3])
print(cs)
```

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

### Sample and Access Configuration Values

Source: https://github.com/automl/configspace/blob/main/docs/reference/configuration.md

Demonstrates creating a ConfigurationSpace, sampling a configuration, and accessing its items.

```python
from ConfigSpace import ConfigurationSpace

cs = ConfigurationSpace(
    {
        "a": (0, 10),
        "b": ["cat", "dog"],
    }
)
configuration = cs.sample_configuration()

for name, value in configuration.items():
    print(f"{name}: {value}")

print(configuration["a"])
```

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

### Create and Sample ConfigurationSpace

Source: https://github.com/automl/configspace/blob/main/docs/index.md

Demonstrates creating a basic ConfigurationSpace with uniform float, integer, and categorical hyperparameters and sampling configurations from it.

```python
from ConfigSpace import ConfigurationSpace

cs = ConfigurationSpace({
    "myfloat": (0.1, 1.5),                # Uniform Float
    "myint": (2, 10),                     # Uniform Integer
    "species": ["mouse", "cat", "dog"],   # Categorical
})
configs = cs.sample_configuration(2)
print(configs)
```

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

### Create and Sample Configuration Space

Source: https://github.com/automl/configspace/blob/main/README.md

Demonstrates the creation of a configuration space with different parameter types (float, integer, categorical) and sampling configurations.

```python
from ConfigSpace import ConfigurationSpace

cs = ConfigurationSpace(
    name="myspace",
    space={
        "a": (0.1, 1.5),  # UniformFloat
        "b": (2, 10),  # UniformInt
        "c": ["mouse", "cat", "dog"],  # Categorical
    },
)

configs = cs.sample_configuration(2)
```

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

### Sample Configuration

Source: https://github.com/automl/configspace/blob/main/docs/quickstart.md

Generate a random configuration from the defined space.

```python
config = cs.sample_configuration()
print(config)
```

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

### Create ConfigurationSpace with Inferred and Simple Hyperparameters

Source: https://context7.com/automl/configspace/llms.txt

Demonstrates defining search spaces using inferred tuples/lists for quick prototyping and explicit helper functions for advanced control.

```python
from ConfigSpace import ConfigurationSpace, Float, Integer, Categorical, Normal

# Method 1: Inferred hyperparameters (quickest for prototyping)
cs_inferred = ConfigurationSpace(
    name="simple_space",
    seed=42,
    space={
        "learning_rate": (0.0001, 0.1),   # Float (tuple with floats)
        "batch_size": (16, 128),           # Integer (tuple with ints)
        "optimizer": ["adam", "sgd", "rmsprop"],  # Categorical (list)
    }
)

# Method 2: Simple hyperparameters (more control)
cs_simple = ConfigurationSpace(
    name="advanced_space",
    seed=42,
    space={
        "lr": Float("lr", bounds=(1e-5, 1e-1), log=True, default=1e-3),
        "epochs": Integer("epochs", bounds=(10, 200), default=100),
        "activation": Categorical("activation", ["relu", "tanh", "sigmoid"],
                                  weights=[0.5, 0.3, 0.2]),
        "dropout": Float("dropout", bounds=(0.0, 0.5),
                         distribution=Normal(mu=0.25, sigma=0.1)),
    }
)

# Sample configurations
config = cs_simple.sample_configuration()
print(f"Sampled config: {dict(config)}")
# Output: Sampled config: {'lr': 0.0003, 'epochs': 87, 'activation': 'relu', 'dropout': 0.31}

# Sample multiple configurations
configs = cs_simple.sample_configuration(5)
for i, c in enumerate(configs):
    print(f"Config {i}: lr={c['lr']:.6f}, epochs={c['epochs']}")
```

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

### Sample Configurations

Source: https://github.com/automl/configspace/blob/main/docs/quickstart.md

Generates random configurations from the defined parent space.

```python
configs = cs.sample_configuration(4)
print(configs)
```

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

### Manage Configuration Objects

Source: https://context7.com/automl/configspace/llms.txt

Demonstrates dictionary-like access, modification, and vector conversion for Configuration objects.

```python
from ConfigSpace import ConfigurationSpace, Configuration, Float, Integer, Categorical
import numpy as np

cs = ConfigurationSpace(
    seed=42,
    space={
        "learning_rate": Float("learning_rate", bounds=(1e-5, 1.0), log=True),
        "num_epochs": Integer("num_epochs", bounds=(10, 200)),
        "optimizer": Categorical("optimizer", items=["adam", "sgd", "adamw"])
    }
)

# Sample a configuration
config = cs.sample_configuration()

# Dictionary-like access
print(f"Learning rate: {config['learning_rate']}")
print(f"Optimizer: {config['optimizer']}")

# Iterate over active parameters
for key, value in config.items():
    print(f"  {key}: {value}")

# Convert to dictionary
config_dict = dict(config)
print(f"As dict: {config_dict}")

# Modify a configuration value
config['learning_rate'] = 0.001
print(f"Modified LR: {config['learning_rate']}")

# Get the internal vector representation (for optimizers)
vector = config.get_array()
print(f"Vector representation: {vector}")

# Create configuration from values
manual_config = Configuration(
    cs,
    values={
        "learning_rate": 0.01,
        "num_epochs": 100,
        "optimizer": "adam"
    }
)
print(f"Manual config: {dict(manual_config)}")

# Create configuration from vector
vector_config = Configuration(cs, vector=np.array([0.5, 0.5, 0.0]))
print(f"Vector config: {dict(vector_config)}")
```

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

### Initialize ConfigurationSpace with Hyperparameters

Source: https://github.com/automl/configspace/blob/main/docs/guide.md

Creates a ConfigurationSpace object with defined float and integer hyperparameter ranges.

```python
from ConfigSpace import ConfigurationSpace

cs = ConfigurationSpace(
    space={
        "C": (-1.0, 1.0),  # Note the decimal to make it a float
        "max_iter": (10, 100),
    },
    seed=1234,
)
print(cs)
```

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

### Initialize ConfigurationSpace

Source: https://github.com/automl/configspace/blob/main/docs/quickstart.md

Create a new ConfigurationSpace instance with a defined hyperparameter range and seed.

```python
from ConfigSpace import ConfigurationSpace, Float

cs = ConfigurationSpace(space={"alpha": (0.0, 1.0)}, seed=1234)
print(cs)
```

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

### Sample Hyperparameter Values

Source: https://context7.com/automl/configspace/llms.txt

Demonstrates how to sample multiple values from an existing hyperparameter.

```python
samples = cs['hidden_size'].sample_value(size=5)
print(f"Hidden size samples: {samples}")
# Output: Hidden size samples: [128, 512, 64, 256, 89]
```

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

### Sample from a Beta distribution using scipy

Source: https://github.com/automl/configspace/blob/main/docs/reference/hyperparameters.md

Demonstrates basic sampling from a continuous beta distribution using scipy.

```python
from scipy.stats import beta as spbeta

alpha, beta = 3, 2
beta_rv = spbeta(alpha, beta)
samples = beta_rv.rvs(size=5)
print(samples)
```

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

### Serialize ConfigurationSpace to YAML and Load

Source: https://github.com/automl/configspace/blob/main/docs/guide.md

Saves a ConfigurationSpace object to a YAML file and then loads it back, demonstrating serialization and deserialization capabilities.

```python
from pathlib import Path
from ConfigSpace import ConfigurationSpace

path = Path("configspace.yaml")
cs = ConfigurationSpace(
    space={
        "C": (-1.0, 1.0),  # Note the decimal to make it a float
        "max_iter": (10, 100),
    },
    seed=1234,
)
cs.to_yaml(path)
loaded_cs = ConfigurationSpace.from_yaml(path)

with path.open() as f:
    print(f.read())
path.unlink()  # markdown-exec: hide
```

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

### Initialize BetaIntegerHyperparameter

Source: https://github.com/automl/configspace/blob/main/docs/reference/hyperparameters.md

Use this to initialize a BetaIntegerHyperparameter. Ensure alpha and beta are >= 1. The default value is calculated based on the distribution's mode if not provided.

```python
def __init__(
        self,
        name: str,
        alpha: Number,
        beta: Number,
        lower: Number,
        upper: Number,
        default_value: Number | None = None,
        log: bool = False,
        meta: Mapping[Hashable, Any] | None = None,
    ) -> None:
        if (alpha < 1) or (beta < 1):
            raise ValueError(
                "Please provide values of alpha and beta larger than or equal to"
                "1 so that the probability density is finite.",
            )
        self.alpha = float(alpha)
        self.beta = float(beta)
        self.lower = int(np.rint(lower))
        self.upper = int(np.rint(upper))
        self.log = bool(log)

        # Create the transformer
        try:
            scaler = UnitScaler(i64(self.lower), i64(self.upper), log=log, dtype=i64)
        except ValueError as e:
            raise ValueError(f"Hyperparameter '{name}' has illegal settings") from e


        if default_value is None:
            # Get the mode of the distribution for setting a default
            if (self.alpha > 1) or (self.beta > 1):
                vectorized_mode = (self.alpha - 1) / (self.alpha + self.beta - 2)
            else:
                # If both alpha and beta are 1, we have a uniform distribution.
                vectorized_mode = 0.5

            _default_value = np.rint(
                scaler.to_value(np.array([vectorized_mode]))[0],
            ).astype(i64)
        else:
            if not is_close_to_integer_single(default_value):
                raise TypeError(
                    f"`default_value` for hyperparameter '{name}' must be an integer."
                    f" Got '{type(default_value).__name__}' for {default_value=}.",
                )

            _default_value = np.rint(default_value).astype(i64)

        size = int(self.upper - self.lower + 1)
        vector_dist = DiscretizedContinuousScipyDistribution(
            rv=spbeta(self.alpha, self.beta),  # type: ignore
            steps=size,
            lower_vectorized=f64(0.0),
            upper_vectorized=f64(1.0),
        )

        super().__init__(
            name=name,
            size=size,
            default_value=_default_value,
            meta=meta,
            transformer=scaler,
            vector_dist=vector_dist,
            neighborhood=vector_dist.neighborhood,
            # Tell ConfigSpace we expect an `int` when giving back a single value
            # For a np.ndarray of values, this will be `np.int64`
            value_cast=int,
            # This method comes from the IntegerHyperparameter
            # you can implement this you self if you'd like
            neighborhood_size=self._integer_neighborhood_size,
        )
```

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

### Serialize and Deserialize ConfigSpace to YAML

Source: https://github.com/automl/configspace/blob/main/docs/reference/serialization.md

Use `to_yaml()` to save a ConfigurationSpace to a YAML file and `from_yaml()` to load it back. Ensure the file path is correct.

```python
cs.to_yaml("configspace.yaml")
cs = ConfigurationSpace.from_yaml("configspace.yaml")
```

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

### Access Default Configuration and Space Properties

Source: https://context7.com/automl/configspace/llms.txt

Retrieve default configurations, estimate the size of the configuration space, and inspect its structural properties like hyperparameters and conditions.

```python
from ConfigSpace import ConfigurationSpace, Float, Integer, Categorical, EqualsCondition

cs = ConfigurationSpace(
    name="example_space",
    seed=42,
    space={
        "algo": Categorical("algo", items=["a", "b", "c"], default="a"),
        "lr": Float("lr", bounds=(0.001, 1.0), default=0.01),
        "layers": Integer("layers", bounds=(1, 10), default=3),
    }
)

# Conditional hyperparameter
depth = Integer("depth", bounds=(1, 5), default=2)
cs.add(depth)
cs.add(EqualsCondition(depth, cs["algo"], "b"))

# Get default configuration
default_config = cs.get_default_configuration()
print(f"Default config: {dict(default_config)}")
# Output: Default config: {'algo': 'a', 'lr': 0.01, 'layers': 3}

# Estimate configuration space size
size = cs.estimate_size()
print(f"Estimated space size: {size}")
# Output: Estimated space size: inf (due to continuous Float)

# Access hyperparameters
print(f"Hyperparameter names: {list(cs.keys())}")
print(f"Number of hyperparameters: {len(cs)}")

# Check conditional structure
print(f"Conditional HPs: {cs.conditional_hyperparameters}")
print(f"Unconditional HPs: {cs.unconditional_hyperparameters}")

# Get parent/child relationships
print(f"Parents of 'depth': {[p.name for p in cs.parents_of['depth']]}")
print(f"Children of 'algo': {[c.name for c in cs.children_of['algo']]}")

# Get conditions
print(f"Conditions: {cs.conditions}")

# Get active hyperparameters for a configuration
config = cs.sample_configuration()
active = cs.get_active_hyperparameters(config)
print(f"Active hyperparameters: {active}")
```

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

### Sample from DiscretizedContinuousScipyDistribution

Source: https://github.com/automl/configspace/blob/main/docs/reference/hyperparameters.md

Demonstrates sampling from a discretized continuous Scipy distribution. Ensure vectorized values are np.float64.

```python
import numpy as np
from scipy.stats import beta as spbeta
from ConfigSpace.hyperparameters.distributions import DiscretizedContinuousScipyDistribution
from ConfigSpace.hyperparameters.hp_components import UnitScaler

# Define the distribution sampler
alpha, beta = 3, 2
vector_distribution = DiscretizedContinuousScipyDistribution(
    rv=spbeta(alpha, beta),
    steps=5,
    lower_vectorized=np.float64(0),
    upper_vectorized=np.float64(1),
)
vector_samples = vector_distribution.sample_vector(n=5)
print(vector_samples)

# Define the transformer from the samplers range to the range we care about
transformer = UnitScaler(
    lower_value=np.int64(1),
    upper_value=np.int64(5),
    dtype=np.int64,  # We want integers in value space
    log=False,
)
integer_values = transformer.to_value(vector_samples)
print(integer_values)

back_to_vector = transformer.to_vector(integer_values)
print(back_to_vector)
```

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

### Serialize and Deserialize ConfigSpace to JSON

Source: https://github.com/automl/configspace/blob/main/docs/reference/serialization.md

Use `to_json()` to save a ConfigurationSpace to a JSON file and `from_json()` to load it back. Ensure the file path is correct.

```python
from ConfigSpace import ConfigurationSpace
cs = ConfigurationSpace({"a": (0, 10), "b": ["cat", "dog"]})
cs.to_json("configspace.json")
cs = ConfigurationSpace.from_json("configspace.json")
```

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

### Serialization Methods

Source: https://github.com/automl/configspace/blob/main/docs/reference/serialization.md

Methods for serializing and deserializing ConfigurationSpace objects to and from JSON, YAML, and dictionary formats.

```APIDOC
## Serialization Methods

### Description
Provides functionality to save and load ConfigurationSpace configurations using JSON, YAML, or Python dictionaries.

### Methods
- `to_json(path)`: Serializes to JSON file.
- `from_json(path)`: Deserializes from JSON file.
- `to_yaml(path)`: Serializes to YAML file.
- `from_yaml(path)`: Deserializes from YAML file.
- `to_serialized_dict()`: Exports as a plain dictionary.
- `from_serialized_dict(dict)`: Imports from a plain dictionary.

### Custom Encoding/Decoding
- **encoders**: Dictionary of `type: (type_name_as_str, encoder_callable)` to override default serialization.
- **decoders**: Dictionary of `{"hyperparameters"|"conditions"|"forbiddens": {type_name: decoder_callable}}` to override default deserialization.
```

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

### Access Configuration Parameters

Source: https://github.com/automl/configspace/blob/main/docs/guide.md

Iterates through configuration items or accesses specific parameters using dictionary-like syntax.

```python
for key, value in config.items():
    print(f"{key}: {value}")

print(config["C"])
```

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

### Read and Write ConfigSpace in PCS format

Source: https://github.com/automl/configspace/blob/main/docs/reference/serialization.md

Use `ConfigSpace.read_and_write.pcs_new.read()` to load a configuration space from a PCS file and `ConfigSpace.read_and_write.pcs_new.write()` to save it. Note that PCS is a legacy format and may issue deprecation warnings.

```python
from ConfigSpace.read_and_write import pcs_new

# Example usage (assuming pcs_new.read and pcs_new.write are available)
# pcs_new.read('path/to/config.pcs')
# pcs_new.write('path/to/output.pcs', configuration_space_object)
```

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

### Process Sampled Configurations

Source: https://github.com/automl/configspace/blob/main/docs/quickstart.md

Iterates through sampled configurations to instantiate the corresponding model objects.

```python
models = []

for config in configs:
    config_as_dict = dict(config)
    model_type = config_as_dict.pop("model")

    model = ModelA(**config_as_dict) if model_type == "A" else ModelB(**config_as_dict)

    models.append(model)

print(models)
```

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

### Advanced Hyperparameter Types

Source: https://github.com/automl/configspace/blob/main/docs/index.md

Demonstrates the use of advanced hyperparameter types like Constant and custom dataclasses or functions within a ConfigurationSpace. Note the removal of the 'q' parameter.

```python
from dataclasses import dataclass
from ConfigSpace import ConfigurationSpace, Constant

@dataclass
class A:
    a: int

def f() -> None:
    return None

cs = ConfigurationSpace({
    "cat": [True, False, None],
    "othercat": [A(1), f],
    "constant": Constant("constant": (24, 25)),
})
```

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

### Define Categorical and Conditional Hyperparameters

Source: https://github.com/automl/configspace/blob/main/docs/guide.md

Initializes a ConfigurationSpace with categorical and conditional hyperparameters for an SVM model. Includes `Categorical`, `Integer`, `Float` types and prints the initial configuration space.

```python
from ConfigSpace import ConfigurationSpace, Categorical, Float, Integer

kernel_type = Categorical('kernel_type', ['linear', 'poly', 'rbf', 'sigmoid'])
degree = Integer('degree', bounds=(2, 4), default=2)
coef0 = Float('coef0', bounds=(0, 1), default=0.0)
gamma = Float('gamma', bounds=(1e-5, 1e2), default=1, log=True)

cs = ConfigurationSpace()
cs.add([kernel_type, degree, coef0, gamma])
print(cs)
```

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

### Define Integer Hyperparameters

Source: https://github.com/automl/configspace/blob/main/docs/reference/hyperparameters.md

Creates a configuration space with integer hyperparameters using uniform, normal, and logarithmic distributions.

```python
from ConfigSpace import Integer, ConfigurationSpace, Uniform, Normal

cs = ConfigurationSpace()

cs.add(
    Integer("a", (0, 10), log=False),
    Integer("b", (0, 10), log=False, distribution=Uniform(), default=5),
    Integer("c", (1, 1000), log=True, distribution=Normal(mu=200, sigma=200)),
)
print(cs)
print(cs["a"].sample_value(size=5))
```

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

### Conditional Hyperparameters

Source: https://github.com/automl/configspace/blob/main/docs/index.md

Illustrates setting up conditional hyperparameters where one hyperparameter's availability or value depends on another's. This requires defining the hyperparameters and then adding an EqualsCondition.

```python
from ConfigSpace import Categorical, ConfigurationSpace, EqualsCondition, Float

cs = ConfigurationSpace(seed=1234)

c = Categorical("c1", items=["a", "b"])
f = Float("f1", bounds=(1.0, 10.0))

# A condition where `f` is only active if `c` is equal to `a` when sampled
cond = EqualsCondition(f, c, "a")

# Add them explicitly to the configuration space
cs.add([c, f])
cs.add(cond)

print(cs)
```

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

### POST /automl/configspace/beta-integer-hyperparameter

Source: https://github.com/automl/configspace/blob/main/docs/reference/hyperparameters.md

Initializes a new BetaIntegerHyperparameter instance with specified distribution parameters and bounds.

```APIDOC
## POST /automl/configspace/beta-integer-hyperparameter

### Description
Initializes a BetaIntegerHyperparameter. This hyperparameter uses a Beta distribution (alpha, beta) to sample integer values within a specified range [lower, upper].

### Method
POST

### Parameters
#### Request Body
- **name** (str) - Required - The name of the hyperparameter.
- **alpha** (Number) - Required - Alpha parameter for the Beta distribution (must be >= 1).
- **beta** (Number) - Required - Beta parameter for the Beta distribution (must be >= 1).
- **lower** (Number) - Required - The lower bound of the integer range.
- **upper** (Number) - Required - The upper bound of the integer range.
- **default_value** (Number) - Optional - The default value for the hyperparameter.
- **log** (bool) - Optional - Whether to use a logarithmic scale.
- **meta** (Mapping) - Optional - Metadata associated with the hyperparameter.

### Request Example
{
  "name": "my_int_param",
  "alpha": 2.0,
  "beta": 5.0,
  "lower": 0,
  "upper": 100,
  "log": false
}

### Response
#### Success Response (200)
- **status** (string) - Confirmation of hyperparameter creation.
```

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

### Assemble Parent Configuration Space

Source: https://github.com/automl/configspace/blob/main/docs/quickstart.md

Combines individual model subspaces into a parent space using conditional activation based on a model selection hyperparameter.

```python
from ConfigSpace import ConfigurationSpace, Categorical

cs = ConfigurationSpace(
    seed=123456,
    space={
        "model": Categorical("model", ["A", "B"], default="A", weights=[1, 2]),
    }
)

# We set the prefix and delimiter to be empty string "" so that we don't have to do
# any extra parsing once sampling
cs.add_configuration_space(
    prefix="",
    delimiter="",
    configuration_space=ModelA.space(),
    parent_hyperparameter={"parent": cs["model"], "value": "A"},
)

cs.add_configuration_space(
    prefix="",
    delimiter="",
    configuration_space=ModelB.space(),
    parent_hyperparameter={"parent": cs["model"], "value": "B"}
)
print(cs)
```

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

### Define Hyperparameters with Distributions

Source: https://github.com/automl/configspace/blob/main/docs/index.md

Shows how to define hyperparameters using specific types like Float, Integer, and Categorical, including custom distributions (Normal) and sampling options (log, weights).

```python
from ConfigSpace import ConfigurationSpace, Integer, Float, Categorical, Normal

cs = ConfigurationSpace(
    name="myspace",
    seed=1234,
    space={
        "a": Float("a", bounds=(0.1, 1.5), distribution=Normal(1, 0.5)),
        "b": Integer("b", bounds=(1, 10_00), log=True, default=100),
        "c": Categorical("c", ["mouse", "cat", "dog"], weights=[2, 1, 1]),
    },
)
configs = cs.sample_configuration(2)
print(configs)
```

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

### Serialize and Deserialize Configuration Space to JSON/YAML

Source: https://context7.com/automl/configspace/llms.txt

Save and load configuration spaces using JSON or YAML formats for reproducibility and sharing. Supports serialization to and from dictionaries.

```python
from pathlib import Path
from ConfigSpace import ConfigurationSpace, Float, Integer, Categorical, EqualsCondition

# Create a configuration space
cs = ConfigurationSpace(name="ml_pipeline", seed=42)

model = Categorical("model", items=["svm", "rf", "xgb"])
lr = Float("lr", bounds=(1e-5, 1.0), log=True)
n_estimators = Integer("n_estimators", bounds=(10, 500))

cs.add([model, lr, n_estimators])
cs.add(EqualsCondition(n_estimators, model, "rf"))
cs.add(EqualsCondition(n_estimators, model, "xgb"))

# Save to JSON
cs.to_json("config_space.json")

# Save to YAML
cs.to_yaml("config_space.yaml")

# Load from JSON
loaded_cs = ConfigurationSpace.from_json("config_space.json")

# Load from YAML
loaded_cs_yaml = ConfigurationSpace.from_yaml("config_space.yaml")

# Verify loaded space works correctly
config = loaded_cs.sample_configuration()
print(f"Loaded and sampled: {dict(config)}")

# Get serialized dictionary (for custom serialization)
serialized_dict = cs.to_serialized_dict()
print(f"Serialized keys: {serialized_dict.keys()}")
# Output: dict_keys(['name', 'hyperparameters', 'conditions', 'forbiddens', 'python_module_version', 'format_version'])

# Restore from dictionary
restored_cs = ConfigurationSpace.from_serialized_dict(serialized_dict)

# Clean up
Path("config_space.json").unlink(missing_ok=True)
Path("config_space.yaml").unlink(missing_ok=True)
```

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

### Check Configuration Validity

Source: https://context7.com/automl/configspace/llms.txt

Use this method to validate a configuration against its defined space. It raises an exception if the configuration is invalid.

```python
manual_config.check_valid_configuration()
```

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

### Define a configuration space with priors

Source: https://github.com/automl/configspace/blob/main/docs/guide.md

Configures a search space for an MLP with specific prior distributions for learning rate, dropout, and activation functions.

```python
import numpy as np
from ConfigSpace import ConfigurationSpace, Float, Categorical, Beta, Normal

cs = ConfigurationSpace(
    space={
        "lr": Float(
            'lr',
            bounds=(1e-5, 1e-1),
            default=1e-3,
            log=True,
            distribution=Normal(1e-3, 1e-1)
        ),
        "dropout": Float(
            'dropout',
            bounds=(0, 0.99),
            default=0.25,
            distribution=Beta(alpha=2, beta=4)
        ),
        "activation": Categorical(
            'activation',
            items=['tanh', 'relu'],
            weights=[0.2, 0.8]
        ),
    },
    seed=1234,
)
print(cs)
```

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

### Define Float Hyperparameters

Source: https://github.com/automl/configspace/blob/main/docs/reference/hyperparameters.md

Creates a configuration space with float hyperparameters using uniform, normal, and logarithmic distributions.

```python
from ConfigSpace import Float, ConfigurationSpace, Uniform, Normal

cs = ConfigurationSpace()

cs.add(
    Float("a", (0, 10), log=False),
    Float("b", (0, 10), log=False, distribution=Uniform(), default=5),
    Float("c", (1, 1000), log=True, distribution=Normal(mu=200, sigma=200)),
)
print(cs)
print(cs["a"].sample_value(size=5))
```

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

### Define Categorical Hyperparameters

Source: https://context7.com/automl/configspace/llms.txt

Shows how to create categorical hyperparameters, including weighted, ordered, and custom object types.

```python
from ConfigSpace import ConfigurationSpace, Categorical

cs = ConfigurationSpace(seed=42)

# Simple categorical
optimizer = Categorical("optimizer", items=["adam", "sgd", "adamw", "rmsprop"])

# Weighted categorical (adam sampled 50% of the time)
optimizer_weighted = Categorical("optimizer_weighted",
                                  items=["adam", "sgd", "adamw"],
                                  weights=[0.5, 0.3, 0.2],
                                  default="adam")

# Ordered categorical (ordinal) - for sizes/levels with inherent order
model_size = Categorical("model_size",
                         items=["tiny", "small", "medium", "large", "xlarge"],
                         ordered=True,
                         default="medium")

# Boolean as categorical
use_dropout = Categorical("use_dropout", items=[True, False],
                          weights=[0.7, 0.3])

cs.add([optimizer, optimizer_weighted, model_size, use_dropout])

# Sample and use
config = cs.sample_configuration()
print(f"Optimizer: {config['optimizer']}")
print(f"Model size: {config['model_size']}")
print(f"Use dropout: {config['use_dropout']}")

# Categorical can hold any Python objects
from dataclasses import dataclass

@dataclass
class Activation:
    name: str
    alpha: float = 0.0

custom_cat = Categorical("activation", items=[
    Activation("relu"),
    Activation("leaky_relu", alpha=0.1),
    Activation("elu", alpha=1.0)
])
```

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

### Define Categorical Hyperparameters

Source: https://github.com/automl/configspace/blob/main/docs/reference/hyperparameters.md

Creates a configuration space with categorical hyperparameters, supporting weights and ordered choices.

```python
from ConfigSpace import Categorical, ConfigurationSpace

cs = ConfigurationSpace()

cs.add(
    Categorical("a", ["cat", "dog", "mouse"], default="dog"),
    Categorical("b", ["small", "medium", "large"], ordered=True, default="medium"),
    Categorical("c", [True, False], weights=[0.2, 0.8]),
)
print(cs)
print(cs["c"].sample_value(size=5))
```

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

### Add Parsed Constraints to ConfigurationSpace

Source: https://context7.com/automl/configspace/llms.txt

Applies conditions and forbidden configurations to an existing space.

```python
cs.add([condition, forbidden])
print(f"Space with parsed constraints:\n{cs}")
```

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

### Define Configuration Space for Linear SVM

Source: https://github.com/automl/configspace/blob/main/docs/guide.md

Sets up a ConfigSpace with categorical and constant hyperparameters for a linear SVM model. This is a prerequisite for defining forbidden clauses.

```python
from ConfigSpace import ConfigurationSpace, Categorical, Constant

cs = ConfigurationSpace()

penalty = Categorical("penalty", ["l1", "l2"], default="l2")
loss = Categorical("loss", ["hinge", "squared_hinge"], default="squared_hinge")
dual = Constant("dual", "False")
cs.add([penalty, loss, dual])
print(cs)
```

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

### Define Direct Hyperparameter Types

Source: https://context7.com/automl/configspace/llms.txt

Demonstrates the creation of various hyperparameter types including float, integer, categorical, and ordinal distributions with custom parameters.

```python
from ConfigSpace import ConfigurationSpace
from ConfigSpace.hyperparameters import (
    UniformFloatHyperparameter,
    UniformIntegerHyperparameter,
    NormalFloatHyperparameter,
    BetaFloatHyperparameter,
    BetaIntegerHyperparameter,
    CategoricalHyperparameter,
    OrdinalHyperparameter,
    Constant
)

cs = ConfigurationSpace(seed=42)

# Uniform float with all parameters
lr = UniformFloatHyperparameter(
    name="learning_rate",
    lower=1e-6,
    upper=1.0,
    default_value=0.001,
    log=True,
    meta={"description": "Learning rate for optimizer"}
)

# Normal distribution float
temp = NormalFloatHyperparameter(
    name="temperature",
    lower=0.0,
    upper=2.0,
    mu=1.0,
    sigma=0.3,
    default_value=1.0,
    log=False
)

# Beta distribution integer
layers = BetaIntegerHyperparameter(
    name="num_layers",
    lower=1,
    upper=20,
    alpha=2,
    beta=5,
    default_value=4
)

# Categorical with weights
optimizer = CategoricalHyperparameter(
    name="optimizer",
    choices=["adam", "sgd", "adamw", "lamb"],
    default_value="adam",
    weights=[0.4, 0.2, 0.3, 0.1]
)

# Ordinal (ordered categorical)
priority = OrdinalHyperparameter(
    name="priority",
    sequence=["low", "medium", "high", "critical"],
    default_value="medium"
)

cs.add([lr, temp, layers, optimizer, priority])

# Access hyperparameter properties
print(f"LR bounds: [{lr.lower}, {lr.upper}], log={lr.log}")
print(f"Temp distribution: mu={temp.mu}, sigma={temp.sigma}")
print(f"Optimizer choices: {optimizer.choices}")
print(f"Priority sequence: {priority.sequence}")

# Sample from individual hyperparameters
print(f"LR samples: {lr.sample_value(size=5)}")
print(f"Layer samples: {layers.sample_value(size=5)}")
```

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

### Define Model Data Structures

Source: https://github.com/automl/configspace/blob/main/docs/quickstart.md

Defines the basic dataclasses for ModelA and ModelB to represent the configuration schema.

```python
from typing import Literal
from dataclasses import dataclass

@dataclass
class ModelA:
    alpha: float
    """Some value between 0 and 1"""

@dataclass
class ModelB:
    kernel: Literal["rbf", "flooper"]
    """Kernel type."""

    kernel_floops: int | None = None
    """Number of floops for the flooper kernel, only used if kernel == "flooper"."""
```

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

### Combine Configuration Spaces Hierarchically

Source: https://context7.com/automl/configspace/llms.txt

Uses add_configuration_space to merge sub-spaces into a main configuration space with conditional logic based on a parent hyperparameter.

```python
from ConfigSpace import ConfigurationSpace, Categorical, Float, Integer, EqualsCondition

# Create sub-spaces for different model types
def create_linear_space():
    cs = ConfigurationSpace()
    cs.add([
        Float("regularization", bounds=(1e-5, 1.0), log=True),
        Categorical("penalty", items=["l1", "l2", "elasticnet"])
    ])
    return cs

def create_neural_space():
    cs = ConfigurationSpace()
    cs.add([
        Integer("hidden_layers", bounds=(1, 5)),
        Integer("hidden_units", bounds=(32, 512), log=True),
        Float("dropout", bounds=(0.0, 0.5)),
        Categorical("activation", items=["relu", "tanh", "gelu"])
    ])
    return cs

# Main configuration space
main_cs = ConfigurationSpace(name="model_selection", seed=42)

# Model type selector
model_type = Categorical("model_type", items=["linear", "neural"], default="neural")
main_cs.add(model_type)

# Add sub-spaces with conditions
main_cs.add_configuration_space(
    prefix="linear",
    delimiter=":",
    configuration_space=create_linear_space(),
    parent_hyperparameter={"parent": main_cs["model_type"], "value": "linear"}
)

main_cs.add_configuration_space(
    prefix="neural",
    delimiter=":",
    configuration_space=create_neural_space(),
    parent_hyperparameter={"parent": main_cs["model_type"], "value": "neural"}
)

# Sample - only relevant sub-space params are active
config = main_cs.sample_configuration()
print(f"Model type: {config['model_type']}")
if config['model_type'] == 'neural':
    print(f"Hidden layers: {config['neural:hidden_layers']}")
    print(f"Activation: {config['neural:activation']}")
else:
    print(f"Penalty: {config['linear:penalty']}")
```

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

### ConfigSpace Utility Functions

Source: https://context7.com/automl/configspace/llms.txt

Utilize functions for generating neighborhood configurations, imputing inactive values, and parsing conditional or forbidden expressions from strings.

```python
from ConfigSpace import ConfigurationSpace, Float, Integer, Categorical
from ConfigSpace.util import (
    impute_inactive_values,
    get_one_exchange_neighbourhood,
    parse_expression_from_string
)
import numpy as np

# Setup
cs = ConfigurationSpace(
    seed=42,
    space={
        "x": Float("x", bounds=(0.0, 10.0)),
        "y": Integer("y", bounds=(1, 100)),
        "cat": Categorical("cat", items=["a", "b", "c"])
    }
)

config = cs.sample_configuration()

# Get neighborhood configurations (useful for local search)
neighbors = list(get_one_exchange_neighbourhood(
    configuration=config,
    seed=42,
    num_neighbors=4,  # neighbors per continuous param
    stdev=0.2         # standard deviation for continuous params
))
print(f"Generated {len(neighbors)} neighbors")
for i, neighbor in enumerate(neighbors[:3]):
    print(f"  Neighbor {i}: {dict(neighbor)}")

# Parse expressions from strings (useful for dynamic constraint creation)
condition_str = "cat == 'a' && x > 5.0"
condition = parse_expression_from_string(
    condition_str,
    cs,
    conditional_hyperparameter=cs["y"]
)
print(f"Parsed condition: {condition}")

# Parse forbidden expression
forbidden_str = "x > 8.0 && y < 10"
forbidden = parse_expression_from_string(forbidden_str, cs)
print(f"Parsed forbidden: {forbidden}")
```

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

### Verify hyperparameter priors with pdf_values

Source: https://github.com/automl/configspace/blob/main/docs/guide.md

Uses the pdf_values method to inspect the probability density of specific hyperparameter values.

```python
test_points = np.logspace(-5, -1, 5)
print(test_points)
print(cs['lr'].pdf_values(test_points))
```

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

### Define Simple Hyperparameters

Source: https://github.com/automl/configspace/blob/main/docs/reference/hyperparameters.md

Use simple hyperparameters via helper functions when you need to create a search space for another library.

```python
from ConfigSpace import ConfigurationSpace, Integer, Categorical, Float, Normal

cs = ConfigurationSpace(
    {
        "a": Integer("a", (0, 10), log=False),    # Integer from 0 to 10
        "b": Categorical("b", ["cat", "dog"], ordered=True),  # Ordered categorical with choices "cat" and "dog"
        "c": Float("c", (1e-5, 1e2), log=True),  # Float from 0.0 to 1.0, log scaled
        "d": Float("d", (10, 20), distribution=Normal(15, 2)),  # Float from 10 to 20, normal distribution
    }
)
print(cs)
```

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

### Custom Decoding for CategoricalHyperparameter

Source: https://github.com/automl/configspace/blob/main/docs/reference/serialization.md

Illustrates the structure for a custom decoder function (`my_decoder`) and how to register it with `from_serialized_dict` for decoding custom hyperparameter types.

```python
def my_decoder(
    # The dictionary that needs to be decoded into a type
    d: dict[str, Any],
    # The current state of the ConfigurationSpace being decoded
    space: ConfigurationSpace,
    # A callable to offload decoding of nested types
    decoder: Callable
) -> Any:
    ... # Implementation details for decoding

my_configspace = ConfigurationSpace.from_serialized_dict(
    my_serialized_dict,
    # Overrides the default decoder for CategoricalHyperparameters
    decoders={
        "hyperparameters": {
            "my_category": my_decoder,
        },
        "conditions": {},  # No need to specify, just here for completeness
        "forbiddens": {},  # No need to specify, just here for completeness
    }
)
```

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

### Access Configuration Values

Source: https://github.com/automl/configspace/blob/main/docs/quickstart.md

Iterate over the sampled configuration object as if it were a standard Python dictionary.

```python
for key, value in config.items():
    print(key, value)
```

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

### Implement Subspace Definitions

Source: https://github.com/automl/configspace/blob/main/docs/quickstart.md

Adds static methods to the dataclasses to define the ConfigurationSpace for each model, including conditional constraints.

```python
from typing import Literal
from ConfigSpace import ConfigurationSpace, Categorical, Integer, Float, Normal, EqualsCondition

@dataclass
class ModelA:
    alpha: float
    """Some value between 0 and 1"""

    @staticmethod
    def space() -> ConfigurationSpace:
        return ConfigurationSpace({
            "alpha": Float("alpha", bounds=(0, 1), distribution=Normal(mu=0.5, sigma=0.2))
        })

@dataclass
class ModelB:
    kernel: Literal["rbf", "flooper"]
    """Kernel type."""

    kernel_floops: int | None = None
    """Number of floops for the flooper kernel, only used if kernel == "flooper"."""

    @staticmethod
    def space() -> ConfigurationSpace:
        cs = ConfigurationSpace(
            {
                "kernel": Categorical("kernel", ["rbf", "flooper"], default="rbf", weights=[.75, .25]),
                "kernel_floops": Integer("kernel_floops", bounds=(1, 10)),
            }
        )

        # We have to make sure "kernel_floops" is only active when the kernel is "floops"
        cs.add(EqualsCondition(cs["kernel_floops"], cs["kernel"], "flooper"))

        return cs
```

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

### Discretize a continuous distribution

Source: https://github.com/automl/configspace/blob/main/docs/reference/hyperparameters.md

Uses DiscretizedContinuousScipyDistribution to map continuous beta distribution samples to discrete integer ranges.

```python
import numpy as np
from scipy.stats import beta as spbeta
from ConfigSpace.hyperparameters.distributions import DiscretizedContinuousScipyDistribution

# As before
alpha, beta = 3, 2
beta_rv = spbeta(alpha, beta)


# Declare our value space bounds and how many discrete steps there
# are between them.
value_bounds = (1, 5)
discrete_steps = value_bounds[1] - value_bounds[0] + 1

# Creates a distribution which can discretize the continuous range
# into `size` number of steps, such that we can map the discretized
# vector values into integers in the range that was requested.

# Where possible, it is usually preferable to have vectorized bounds from (0, 1)
```

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

### Define BetaIntegerHyperparameter

Source: https://github.com/automl/configspace/blob/main/docs/reference/hyperparameters.md

Provides the complete implementation for a BetaIntegerHyperparameter using ConfigSpace, dataclasses, and Scipy distributions. This can be a template for custom hyperparameters.

```python
from typing import TypeAlias, Union, Mapping, Hashable, Any
import numpy as np
from scipy.stats import beta as spbeta

from ConfigSpace.hyperparameters import IntegerHyperparameter
from ConfigSpace.hyperparameters.distributions import DiscretizedContinuousScipyDistribution
from ConfigSpace.hyperparameters.hp_components import UnitScaler
from ConfigSpace.functional import is_close_to_integer_single

i64 = np.int64
f64 = np.float64

```

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

### Define Inferred Hyperparameters

Source: https://github.com/automl/configspace/blob/main/docs/reference/hyperparameters.md

Use inferred hyperparameters for simple search spaces or rapid prototyping by passing tuples or lists directly to the ConfigurationSpace constructor.

```python
from ConfigSpace import ConfigurationSpace

cs = ConfigurationSpace(
    {
        "a": (0, 10),    # Integer from 0 to 10
        "b": ["cat", "dog"],  # Categorical with choices "cat" and "dog"
        "c": (0.0, 1.0),  # Float from 0.0 to 1.0
    }
)
print(cs)
```

```python
from ConfigSpace import ConfigurationSpace

cs = ConfigurationSpace(
    {
        "a": (0, 10),    # Integer from 0 to 10
        "b": ["cat", "dog"],  # Categorical with choices "cat" and "dog"
        "c": (0.0, 1.0)  # Float from 0.0 to 1.0
    }
)
print(cs)
```

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

### Define Float Hyperparameters

Source: https://context7.com/automl/configspace/llms.txt

Configures floating-point parameters using uniform, normal, or beta distributions with optional log-scale sampling.

```python
from ConfigSpace import ConfigurationSpace, Float, Normal, Beta, Uniform

cs = ConfigurationSpace(seed=123)

# Uniform distribution (default)
learning_rate = Float("learning_rate", bounds=(1e-5, 1e-1), log=True)

# Normal distribution centered at 0.5
temperature = Float("temperature", bounds=(0.0, 1.0),
                    distribution=Normal(mu=0.5, sigma=0.15),
                    default=0.5)

# Beta distribution (useful for probabilities)
dropout_prob = Float("dropout", bounds=(0.0, 0.8),
                     distribution=Beta(alpha=2, beta=5))

cs.add([learning_rate, temperature, dropout_prob])

# Sample and access values
config = cs.sample_configuration()
print(f"Learning rate: {config['learning_rate']:.6f}")
print(f"Temperature: {config['temperature']:.4f}")
print(f"Dropout: {config['dropout']:.4f}")

# Get probability density for analysis
import numpy as np
test_points = np.linspace(0.0, 0.8, 5)
pdf_values = cs['dropout'].pdf_values(test_points)
print(f"PDF at {test_points}: {pdf_values}")
```

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

### Custom Encoding for CategoricalHyperparameter

Source: https://github.com/automl/configspace/blob/main/docs/reference/serialization.md

Demonstrates how to define and use a custom encoder for `CategoricalHyperparameter` when serializing to a dictionary. This allows for custom representation of choices.

```python
from typing import Any, Callable
from ConfigSpace import ConfigurationSpace, CategoricalHyperparameter

cs = ConfigurationSpace({"a": ["cat", "dog"]})

def my_custom_encoder(
    hp: CategoricalHyperparameter,
    encoder: Callable[[Any], dict],
) -> dict:
    return {
        "name": hp.name,
        "choices": [f"!{c}!" for c in hp.choices],
    }

without_custom_encoder = cs.to_serialized_dict()
with_custom_encoder = cs.to_serialized_dict(
    # Overrides the default encoder for CategoricalHyperparameters
    encoders={
        CategoricalHyperparameter: ("my_category", my_custom_encoder),
    }
)
print(without_custom_encoder)
print("--------")
print(with_custom_encoder)
```

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

### Define Direct Hyperparameters

Source: https://github.com/automl/configspace/blob/main/docs/reference/hyperparameters.md

Use direct hyperparameter classes for maximum customizability, primarily intended for library developers building on top of ConfigSpace.

```python
from ConfigSpace import (
    ConfigurationSpace,
    UniformIntegerHyperparameter,
    CategoricalHyperparameter,
    UniformFloatHyperparameter,
    NormalFloatHyperparameter,
    OrdinalHyperparameter
)

cs = ConfigurationSpace(
    {
        "a": UniformIntegerHyperparameter("a", lower=0, upper=10, log=False),    # Integer from 0 to 10
        "b": CategoricalHyperparameter("b", choices=["cat", "dog"], default_value="dog"),  # Ordered categorical with choices "cat" and "dog"
        "c": UniformFloatHyperparameter("c", lower=1e-5, upper=1e2, log=True),  # Float from 0.0 to 1.0, log scaled
        "d": NormalFloatHyperparameter("d", lower=10, upper=20, mu=15, sigma=2),  # Float from 10 to 20, normal distribution
        "e": OrdinalHyperparameter("e", sequence=["s", "m", "l"], default_value="s"),  # Ordered categorical
    }
)
print(cs)
```