Skip to content

Archive

Quality-diversity archives for storing diverse solutions.

Archive

Bases: ABC, Generic[G]

Abstract base class for quality-diversity archives.

Source code in src/rotalabs_redqueen/core/archive.py 
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
class Archive(ABC, Generic[G]):
    """Abstract base class for quality-diversity archives."""

    @abstractmethod
    def add(self, individual: Individual[G]) -> bool:
        """Try to add an individual to the archive.

        Args:
            individual: Individual to add

        Returns:
            True if added (new cell or better than existing)
        """
        pass

    @abstractmethod
    def get_all(self) -> list[Individual[G]]:
        """Get all individuals in the archive."""
        pass

    @abstractmethod
    def coverage(self) -> ArchiveCoverage:
        """Get archive coverage statistics."""
        pass

add(individual: Individual[G]) -> bool abstractmethod

Try to add an individual to the archive.

Parameters:

Name Type Description Default
individual Individual[G]

Individual to add

 required

Returns:

Type Description
bool

True if added (new cell or better than existing)
Source code in src/rotalabs_redqueen/core/archive.py 
64
65
66
67
68
69
70
71
72
73
74
@abstractmethod
def add(self, individual: Individual[G]) -> bool:
    """Try to add an individual to the archive.

    Args:
        individual: Individual to add

    Returns:
        True if added (new cell or better than existing)
    """
    pass

get_all() -> list[Individual[G]] abstractmethod

Get all individuals in the archive.

Source code in src/rotalabs_redqueen/core/archive.py 
76
77
78
79
@abstractmethod
def get_all(self) -> list[Individual[G]]:
    """Get all individuals in the archive."""
    pass

coverage() -> ArchiveCoverage abstractmethod

Get archive coverage statistics.

Source code in src/rotalabs_redqueen/core/archive.py 
81
82
83
84
@abstractmethod
def coverage(self) -> ArchiveCoverage:
    """Get archive coverage statistics."""
    pass

MapElitesArchive

Bases: Archive[G], Generic[G]

MAP-Elites quality-diversity archive.

Maintains a grid of cells in behavior space, keeping the best individual in each cell.

Source code in src/rotalabs_redqueen/core/archive.py 
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
class MapElitesArchive(Archive[G], Generic[G]):
    """MAP-Elites quality-diversity archive.

    Maintains a grid of cells in behavior space, keeping the best
    individual in each cell.
    """

    def __init__(self, dimensions: list[BehaviorDimension]):
        """Initialize MAP-Elites archive.

        Args:
            dimensions: Configuration for each behavior dimension
        """
        self.dimensions = dimensions
        self.cells: dict[tuple[int, ...], Individual[G]] = {}

    def _get_cell_key(self, behavior: BehaviorDescriptor) -> tuple[int, ...]:
        """Map behavior to cell coordinates.

        Args:
            behavior: Behavior descriptor

        Returns:
            Tuple of bin indices for each dimension
        """
        if len(behavior) != len(self.dimensions):
            raise ValueError(
                f"Behavior has {len(behavior)} dimensions, "
                f"archive has {len(self.dimensions)}"
            )
        return tuple(
            dim.get_bin(behavior[i]) for i, dim in enumerate(self.dimensions)
        )

    def add(self, individual: Individual[G]) -> bool:
        """Try to add an individual to the archive.

        Adds if:
        - Cell is empty, or
        - Individual has higher fitness than current occupant
        """
        key = self._get_cell_key(individual.behavior)

        if key not in self.cells:
            self.cells[key] = individual
            return True

        if individual.fitness > self.cells[key].fitness:
            self.cells[key] = individual
            return True

        return False

    def get(self, behavior: BehaviorDescriptor) -> Individual[G] | None:
        """Get individual at a behavior location.

        Args:
            behavior: Behavior descriptor

        Returns:
            Individual at that cell or None
        """
        key = self._get_cell_key(behavior)
        return self.cells.get(key)

    def get_all(self) -> list[Individual[G]]:
        """Get all individuals in the archive."""
        return list(self.cells.values())

    def best(self) -> Individual[G] | None:
        """Get the best individual in the archive."""
        if not self.cells:
            return None
        return max(self.cells.values(), key=lambda i: i.fitness.value)

    def coverage(self) -> ArchiveCoverage:
        """Get archive coverage statistics."""
        total = 1
        for dim in self.dimensions:
            total *= dim.bins
        return ArchiveCoverage(filled_cells=len(self.cells), total_cells=total)

    def sample_random(self, n: int, rng=None) -> list[Individual[G]]:
        """Sample N random individuals from the archive.

        Args:
            n: Number to sample
            rng: Random number generator

        Returns:
            List of sampled individuals
        """
        import numpy as np

        if rng is None:
            rng = np.random.default_rng()

        individuals = self.get_all()
        if len(individuals) <= n:
            return individuals

        indices = rng.choice(len(individuals), size=n, replace=False)
        return [individuals[i] for i in indices]

__init__(dimensions: list[BehaviorDimension])

Initialize MAP-Elites archive.

Parameters:

Name Type Description Default
dimensions list[BehaviorDimension]

Configuration for each behavior dimension

 required
Source code in src/rotalabs_redqueen/core/archive.py 
 94
 95
 96
 97
 98
 99
100
101
def __init__(self, dimensions: list[BehaviorDimension]):
    """Initialize MAP-Elites archive.

    Args:
        dimensions: Configuration for each behavior dimension
    """
    self.dimensions = dimensions
    self.cells: dict[tuple[int, ...], Individual[G]] = {}

add(individual: Individual[G]) -> bool

Try to add an individual to the archive.

Adds if: - Cell is empty, or - Individual has higher fitness than current occupant

Source code in src/rotalabs_redqueen/core/archive.py 
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
def add(self, individual: Individual[G]) -> bool:
    """Try to add an individual to the archive.

    Adds if:
    - Cell is empty, or
    - Individual has higher fitness than current occupant
    """
    key = self._get_cell_key(individual.behavior)

    if key not in self.cells:
        self.cells[key] = individual
        return True

    if individual.fitness > self.cells[key].fitness:
        self.cells[key] = individual
        return True

    return False

get(behavior: BehaviorDescriptor) -> Individual[G] | None

Get individual at a behavior location.

Parameters:

Name Type Description Default
behavior BehaviorDescriptor

Behavior descriptor

 required

Returns:

Type Description
Individual[G] | None

Individual at that cell or None
Source code in src/rotalabs_redqueen/core/archive.py 
140
141
142
143
144
145
146
147
148
149
150
def get(self, behavior: BehaviorDescriptor) -> Individual[G] | None:
    """Get individual at a behavior location.

    Args:
        behavior: Behavior descriptor

    Returns:
        Individual at that cell or None
    """
    key = self._get_cell_key(behavior)
    return self.cells.get(key)

get_all() -> list[Individual[G]]

Get all individuals in the archive.

Source code in src/rotalabs_redqueen/core/archive.py 
152
153
154
def get_all(self) -> list[Individual[G]]:
    """Get all individuals in the archive."""
    return list(self.cells.values())

best() -> Individual[G] | None

Get the best individual in the archive.

Source code in src/rotalabs_redqueen/core/archive.py 
156
157
158
159
160
def best(self) -> Individual[G] | None:
    """Get the best individual in the archive."""
    if not self.cells:
        return None
    return max(self.cells.values(), key=lambda i: i.fitness.value)

coverage() -> ArchiveCoverage

Get archive coverage statistics.

Source code in src/rotalabs_redqueen/core/archive.py 
162
163
164
165
166
167
def coverage(self) -> ArchiveCoverage:
    """Get archive coverage statistics."""
    total = 1
    for dim in self.dimensions:
        total *= dim.bins
    return ArchiveCoverage(filled_cells=len(self.cells), total_cells=total)

sample_random(n: int, rng=None) -> list[Individual[G]]

Sample N random individuals from the archive.

Parameters:

Name Type Description Default
n int

Number to sample

 required
rng

Random number generator

 None

Returns:

Type Description
list[Individual[G]]

List of sampled individuals
Source code in src/rotalabs_redqueen/core/archive.py 
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
def sample_random(self, n: int, rng=None) -> list[Individual[G]]:
    """Sample N random individuals from the archive.

    Args:
        n: Number to sample
        rng: Random number generator

    Returns:
        List of sampled individuals
    """
    import numpy as np

    if rng is None:
        rng = np.random.default_rng()

    individuals = self.get_all()
    if len(individuals) <= n:
        return individuals

    indices = rng.choice(len(individuals), size=n, replace=False)
    return [individuals[i] for i in indices]

BehaviorDimension

Configuration for one dimension of the behavior space.

Source code in src/rotalabs_redqueen/core/archive.py 
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
@dataclass
class BehaviorDimension:
    """Configuration for one dimension of the behavior space."""

    name: str
    min_value: float
    max_value: float
    bins: int = 10

    def get_bin(self, value: float) -> int:
        """Map a value to a bin index.

        Args:
            value: Value in this dimension

        Returns:
            Bin index (0 to bins-1)
        """
        # Clamp to range
        value = max(self.min_value, min(self.max_value, value))
        # Normalize to [0, 1]
        normalized = (value - self.min_value) / (self.max_value - self.min_value + 1e-10)
        # Map to bin
        bin_idx = int(normalized * self.bins)
        return min(bin_idx, self.bins - 1)

get_bin(value: float) -> int

Map a value to a bin index.

Parameters:

Name Type Description Default
value float

Value in this dimension

 required

Returns:

Type Description
int

Bin index (0 to bins-1)
Source code in src/rotalabs_redqueen/core/archive.py 
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
def get_bin(self, value: float) -> int:
    """Map a value to a bin index.

    Args:
        value: Value in this dimension

    Returns:
        Bin index (0 to bins-1)
    """
    # Clamp to range
    value = max(self.min_value, min(self.max_value, value))
    # Normalize to [0, 1]
    normalized = (value - self.min_value) / (self.max_value - self.min_value + 1e-10)
    # Map to bin
    bin_idx = int(normalized * self.bins)
    return min(bin_idx, self.bins - 1)

ArchiveCoverage

Statistics about archive coverage.

Source code in src/rotalabs_redqueen/core/archive.py 
46
47
48
49
50
51
52
53
54
55
56
57
58
@dataclass
class ArchiveCoverage:
    """Statistics about archive coverage."""

    filled_cells: int
    total_cells: int

    @property
    def coverage_percent(self) -> float:
        """Percentage of cells filled."""
        if self.total_cells == 0:
            return 0.0
        return 100.0 * self.filled_cells / self.total_cells

coverage_percent: float property

Percentage of cells filled.