AISP 0.4.0 (#4)

* docs: adds documentation for AISP 0.4.0
* feat(docs): update docs and include example notebooks
* version: 0.4.x

Author: Joao-Paulo-Silva

docs/advanced-guides/Utils/Display.md

@@ -0,0 +1,152 @@
+# Display
+
+Utility Functions for Displaying Algorithm Information
+
+## def _supports_box_drawing()
+
+```python
+def _supports_box_drawing() -> bool
+```
+
+Function to check if the terminal supports boxed characters.
+
+**Returns**:
+
+* ***bool*** (`bool`): True if the terminal likely supports boxed characters, False otherwise.
+
+---
+
+## class TableFormatter
+
+Class to format tabular data into strings for display in the console.
+
+**Parameters**:
+
+* ***headers*** (`Mapping[str, int]`): Mapping of column names to their respective widths, in the format `{column_name: column_width}`.
+
+**Raises**:
+
+* `ValueError`: If `headers` is empty or not a valid mapping.
+
+---
+
+### def _border(left, middle, right, line, new_line=True)
+
+```python
+def _border(self, left: str, middle: str, right: str, line: str, new_line: bool = True) -> str
+```
+
+Create a horizontal border for the table.
+
+**Parameters**:
+
+* ***left*** (`str`): Character on the left side of the border.
+* ***middle*** (`str`): Character separator between columns.
+* ***right*** (`str`): Character on the right side of the border.
+* ***line*** (`str`): Character used to fill the border.
+* ***new_line*** (`bool`, optional): If True, adds a line break before the border (default is True).
+
+**Returns**:
+
+* ***border*** (`str`): String representing the horizontal border.
+
+---
+
+### def get_header()
+
+```python
+def get_header(self) -> str
+```
+
+Generate the table header, including the top border, column headings, and separator line.
+
+**Returns**:
+
+* ***header*** (`str`): Formatted string of the table header.
+
+---
+
+### def get_row(values)
+
+```python
+def get_row(self, values: Mapping[str, Union[str, int, float]]) -> str
+```
+
+Generate a formatted row for the table data.
+
+**Parameters**:
+
+* ***values*** (`Mapping[str, Union[str, int, float]]`): Dictionary with values for each column, in the format `{column_name: value}`.
+
+**Returns**:
+
+* ***row*** (`str`): Formatted string of the table row.
+
+---
+
+### def get_bottom(new_line=False)
+
+```python
+def get_bottom(self, new_line: bool = False) -> str
+```
+
+Generate the table's bottom border.
+
+**Parameters**:
+
+* ***new_line*** (`bool`, optional): If True, adds a line break before the border (default is False).
+
+**Returns**:
+
+* ***bottom*** (`str`): Formatted string for the bottom border.
+
+---
+
+## class ProgressTable(TableFormatter)
+
+Class to display a formatted table in the console to track the algorithm's progress.
+
+**Parameters**:
+
+* ***headers*** (`Mapping[str, int]`): Mapping `{column_name: column_width}`.
+* ***verbose*** (`bool`): If False, prints nothing to the terminal.
+
+**Raises**:
+
+* `ValueError`: If `headers` is empty or not a valid mapping.
+
+---
+
+### def _print_header()
+
+```python
+def _print_header(self) -> None
+```
+
+Print the table header.
+
+---
+
+### def update(values)
+
+```python
+def update(self, values: Mapping[str, Union[str, int, float]]) -> None
+```
+
+Add a new row of values to the table.
+
+**Parameters**:
+
+* ***values*** (`Mapping[str, Union[str, int, float]]`): Keys must match the columns defined in headers.
+
+---
+
+### def finish()
+
+```python
+def finish(self) -> None
+```
+
+End the table display, printing the bottom border and total time.
+
+---

docs/advanced-guides/Utils/Sanitizers.md

@@ -57,4 +57,26 @@ The function ``sanitize_param(...)``, returns the seed if it is a non-negative i
 * seed (``Any``): The seed value to be validated.
 
 **Returns:**
-* ``Optional[int]``: The original seed if it is a non-negative integer, or ``None`` if it is invalid.
+* ``Optional[int]``: The original seed if it is a non-negative integer, or ``None`` if it is invalid.
+
+---
+
+## def sanitize_bounds(...)
+
+```python
+def sanitize_bounds(
+    bounds: Any, 
+    problem_size: int
+) -> Dict[str, npt.NDArray[np.float64]]
+```
+
+The function ``sanitize_bounds(...)``, validate and normalize feature bounds.
+
+**Parameters:**
+* ***bounds*** (``Any``): he input bounds, which must be either None or a dictionary with 'low' and 'high' keys.
+* ***problem_size*** (``int``): The expected length for the normalized bounds lists, corresponding to the number of features in the problem.
+
+
+**Returns:**
+* `Dict[str, list]`: Dictionary ``{'low': [low_1, ..., low_N], 'high': [high_1, ..., high_N]}``.
+

docs/advanced-guides/base-module/Mutation.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 4
+sidebar_position: 5
 title: Mutation
 sidebar_label: Mutation
 lastUpdatedAt: 2025/04/04
@@ -94,4 +94,32 @@ This function creates `n` clones of the input vector and applies random mutation
 
 ### Returns
 
-* `clone_set` (`npt.NDArray[np.float64]`): Array with shape `(n, len(vector))` containing the `n` mutated clones of the original vector.
+* `clone_set` (`npt.NDArray[np.float64]`): Array with shape `(n, len(vector))` containing the `n` mutated clones of the original vector.
+
+---
+
+## clone_and_mutate_permutation
+
+```python
+@njit([(types.int64[:], types.int64, types.float64)], cache=True)
+def clone___and_mutate_permutation(
+    vector: npt.NDArray[np.int64],
+    n: int,
+    mutation_rate: float
+) -> npt.NDArray[np.int64]:
+```
+
+Generates a set of mutated clones from a permutation vector.
+
+This function creates `n` clones of the input permutation vector and applies random mutations to each one, simulating clonal expansion in artificial immune systems with discrete permutations. Each clone receives a random number of swaps according to the mutation rate.
+
+### Parameters
+
+* `vector` (`npt.NDArray[np.int64]`): The original immune cell with permutation values to be cloned and mutated.
+* `n` (`int`): Number of mutated clones to be generated.
+* `mutation_rate` (`float`): Probability of mutating each component ($$0 <= mutation\_rate < 1$$).
+
+### Returns
+
+* `clone_set` (`npt.NDArray[np.int64]`): Array with shape `(n, len(vector))` containing the `n` mutated clones of the original vector.
+

docs/advanced-guides/base-module/Optimizer.md

@@ -0,0 +1,166 @@
+---
+sidebar_position: 4
+title: Base class for optimization algorithms.
+sidebar_label: BaseOptimizer
+lastUpdatedAt: 2025/08/19
+author: João Paulo
+keywords:
+  - BaseOptimizer
+  - base class
+  - optimization algorithms
+  - abstract base class
+  - machine learning optimization
+  - supervised learning
+  - optimize method
+  - objective function
+  - model evaluation
+  - Python ML classes
+  - Clonalg
+  - metaheuristics
+---
+
+
+This class defines the core interface for optimization strategies and
+keeps track of the cost history, evaluated solutions, and the best solution found. Subclasses must implement
+``optimize`` and ``objective_function``.
+
+---
+
+### Properties
+
+#### `cost_history`
+
+```python
+@property
+def cost_history(self) -> List[float]
+```
+
+Returns the history of costs during optimization.
+
+---
+
+#### `solution_history`
+
+```python
+@property
+def solution_history(self) -> List
+```
+
+Returns the history of evaluated solutions.
+
+---
+
+#### `best_solution`
+
+```python
+@property
+def best_solution(self) -> Optional[Any]
+```
+
+Returns the best solution found so far, or `None` if unavailable.
+
+---
+
+#### `best_cost`
+
+```python
+@property
+def best_cost(self) -> Optional[float]
+```
+
+Returns the cost of the best solution found so far, or `None` if unavailable.
+
+---
+
+## Functions
+
+### Function _record_best(...)
+
+```python
+def _record_best(self, cost: float, best_solution: Any) -> None
+```
+
+Record a new cost value and update the best solution if improved.
+
+**Parameters**:
+  * ***cost***: `float` - Cost value to be added to the history.
+
+---
+
+### Function get_report()
+
+```python
+def get_report(self) -> str
+```
+
+Generate a formatted summary report of the optimization process. The report includes the best solution,
+its associated cost, and the evolution of cost values per iteration.
+
+**Returns**:
+  * **report**: `str` - A formatted string containing the optimization summary.
+
+---
+
+### Function register(...)
+
+```python
+def register(self, alias: str, function: Callable[..., Any]) -> None
+```
+
+Register a function dynamically in the optimizer instance.
+
+**Parameters**:
+  * ***alias***: `str` - Name used to access the function as an attribute.
+  * ***function***: `Callable[..., Any]` - Callable to be registered.
+
+**Raises**:
+  * **TypeError**: If `function` is not callable.
+  * **AttributeError**: If `alias` is protected and cannot be modified, or if `alias` does not exist in the
+     optimizer class.
+
+---
+
+### Function reset()
+
+```python
+def reset(self)
+```
+
+Reset the object's internal state, clearing history and resetting values.
+
+---
+
+### Abstract methods
+
+#### Function optimize(...)
+
+```python
+def optimize(self, max_iters: int = 50, n_iter_no_change=10, verbose: bool = True) -> Any
+```
+
+Execute the optimization process. This method must be implemented by the subclass to define how the optimization strategy explores the search space.
+
+**Parameters**:
+  * ***max_iters***: `int` - Maximum number of iterations.
+  * ***n_iter_no_change***: `int`, default=10 - The maximum number of iterations without updating the best solution.
+  * ***verbose***: `bool`, default=True - Flag to enable or disable detailed output during optimization.
+
+**Implementation**:
+
+* [Clonalg](/docs/aisp-techniques/clonal-selection-algorithms/clonalg#function-optimize)
+
+---
+
+#### Function affinity_function(...)
+
+```python
+def affinity_function(self, solution: Any) -> float
+```
+
+Evaluate the affinity of a candidate solution. This method must be implemented by the subclass to define the problem-specific.
+
+**Parameters**:
+  * ***solution***: `Any` - Candidate solution to be evaluated.
+
+**Returns**:
+  * **cost**: `float` - Cost value associated with the given solution.