tantale_core/

solution.rs

//! # Solution
//!
//! This module defines the [`Solution`] trait and related types representing candidate solutions
//! in the optimization process. Solutions are points sampled from a [`Searchspace`](crate::Searchspace)
//! and form the fundamental data structure manipulated by optimizers and objective functions.
//!
//! ## Core Concepts
//!
//! ### Dual Domain Solutions
//!
//! Following Tantale's dual domain architecture, there are two types of solutions:
//! - **Obj solutions**: In the objective function's domain
//! - **Opt solutions**: In the optimizer's domain
//!
//! [`Twin`](Solution::twin) [`Solution`] are wrapped within a [`SolutionShape`] to maintain the relationship and bounds between both
//! generated `Obj` and `Opt` [`Solution`]s.
//!
//! Each solution is statically typed by its corresponding [`Domain`].
//!
//! ### Solution Components
//!
//! A [`Solution`] consists of three essential components:
//! 1. **Unique [`Id`]**: Identifies the solution and links [`twin`](Solution::twin) representations across domains
//! 2. **[`Raw`](Solution::Raw) data**: The actual variable values in the domain's native type
//! 3. **[`SolInfo`]**: Metadata associated with the solution (e.g., iteration info)
//!
//! ### Twin Solutions
//!
//! Solutions in different domains that represent the same point share an [`Id`], making them "twins":
//! ```ignore
//! let obj_solution = sp.sample_obj(&mut rng, info.clone());
//! let paired = sp.onto_opt(obj_solution); // Creates twin in Opt domain
//! assert_eq!(paired.get_obj().id(), paired.get_opt().id());
//! ```
//!
//! ## Solution States
//!
//! Solutions progress through different states during optimization:
//!
//! - **[`Uncomputed`]**: Generated but not yet evaluated
//! - **[`Computed`]**: Evaluated with an associated [`Codomain`] value
//!
//! The [`IntoComputed`] trait enables conversion from uncomputed to computed states.
//!
//! ## Multi-Fidelity Support
//!
//! For multi-fidelity optimization, solutions can track:
//! - **[`Step`](crate::Step)** progress via [`HasStep`](crate::HasStep)
//! - **[`Fidelity`]** level via [`HasFidelity`](crate::HasFidelity)
//!
//! This enables progressive evaluation and resource allocation strategies.
//!
//! ## Structured solutions
//!
//! Solutions can be arranged in different way:
//! - [`Lone`]: Single-domain solution
//! - [`Pair`]: Paired Obj/Opt solutions
//! - [`Batch`]: Collections of [`SolutionShape`]
//!
//! ## Creation and Usage
//!
//! Solutions are typically created through [`Searchspace`](crate::Searchspace) methods:
//! ```ignore
//! // Sampling creates Uncomputed solutions
//! let solution = sp.sample_opt(&mut rng, info);
//!
//! // Evaluation converts to Computed
//! let outcome = objective_fn(solution.get_x());
//! let computed = solution.into_computed(Arc::new(outcome));
//! ```
//!
//! ## See Also
//!
//! - [`Searchspace`](crate::Searchspace) - Creates and manages solutions
//! - [`Domain`] - Defines solution value types
//! - [`Codomain`] - Defines evaluation result types
//! - [`Id`] - Solution identifier types
//! - [`BaseSol`] - Concrete solution implementations
//! - [`Computed`] - Evaluated solution wrappers
//!

use crate::{
    HasId, HasSolInfo, HasY, Outcome,
    domain::{Domain, codomain::TypeCodom},
    has_trait::HasX,
};

use serde::{Deserialize, Serialize};
use std::{fmt::Debug, sync::Arc};

/// Metadata associated with a solution during optimization.
///
/// [`SolInfo`] provides a way to attach auxiliary information to solutions, such as iteration
/// numbers, timestamps, or optimizer-specific data. This information persists across checkpointing
/// and is available to recorders.
///
/// # Associated Derive Macro
///
/// The `SolInfo` derive macro automatically implements the trait for any struct
/// satisfying the required trait bounds.
pub trait SolInfo: Debug + Serialize + for<'a> Deserialize<'a> {}

/// Core trait representing a candidate solution in the optimization process.
///
/// [`Solution`] is the fundamental abstraction for points in the search space. It combines
/// a unique identifier ([`Id`]), variable values ([`Raw`](Solution::Raw)), and metadata
/// ([`SolInfo`]), with full serialization support for checkpointing.
///
/// # Associated Types
///
/// ## [`Raw`](Solution::Raw)
///
/// The native representation of variable values in this domain. The type depends on the [`Domain`]:
/// - [`Real`](crate::Real): `f64`
/// - [`Nat`](crate::Nat): `i64`
/// - [`Cat`](crate::Cat): `String``
/// - [`Mixed`](crate::Mixed): [`MixedTypeDom`](crate::MixedTypeDom) (heterogeneous values)
///
/// ## [`Twin`](Solution::Twin)
///
/// The solution type in an alternative domain `B`. Twin solutions share the same [`Id`]
/// but have different [`Raw`](Solution::Raw) representations, enabling domain transformations while
/// maintaining solution identity.
///
/// # Concrete Implementations
///
/// - [`BaseSol`] - Standard solution implementation
/// - [`FidelitySol`] - With fidelity support
/// - [`Computed`] - Wrapper for evaluated solutions
pub trait Solution<SolId, Dom, SInfo>
where
    Self: Sized
        + Debug
        + HasX<Self::Raw>
        + HasId<SolId>
        + HasSolInfo<SInfo>
        + Serialize
        + for<'de> Deserialize<'de>,
    SolId: Id,
    SInfo: SolInfo,
    Dom: Domain,
{
    /// The native type representing variable values in this domain.
    ///
    /// This type is determined by the [TypeDom](Domain::TypeDom) from the solution's [`Domain`].
    type Raw: Clone + Debug + Serialize + for<'de> Deserialize<'de>;

    /// Twin solutions share the same [`Id`] but exist in different domains,
    /// enabling transformations between Obj and Opt representations.
    type Twin<B: Domain>: Solution<SolId, B, SInfo, Twin<Dom> = Self>;

    /// Creates a twin solution in a different domain with the same [`Id`].
    ///
    /// This method constructs a solution in domain `B` that shares the same identifier
    /// as `self`, establishing a twin relationship. This is used internally by
    /// [`Searchspace`](crate::Searchspace) when mapping between Obj and Opt domains.
    ///
    /// Twins are usually wrapped within a [`SolutionShape`] to facilitate access and manipulation of both representation.
    fn twin<B: Domain>(
        &self,
        x: <Self::Twin<B> as Solution<SolId, B, SInfo>>::Raw,
    ) -> Self::Twin<B>;

    /// Creates a clone of this solution with the same values, metadata, and [`Id`], used
    /// for [`Accumulator`](crate::domain::codomain::Accumulator).
    fn _clone_sol(&self) -> Self;
}

/// Trait for solutions that have not yet been evaluated.
///
/// [`Uncomputed`] represents solutions generated by sampling or optimization but not yet
/// evaluated by the objective function. These solutions can be converted to [`Computed`]
/// solutions via the [`IntoComputed`] trait and a [`TypeCodom`](Codomain::TypeCodom).
///
/// # Type Parameters
///
/// * `SolId` - The unique identifier type
/// * `Dom` - The domain defining variable types and constraints
/// * `SInfo` - The solution metadata type
///
/// # Lifecycle
///
/// ```text
///        Uncomputed --[evaluate]-> Computed
///              ^                       |
///              |                       |
/// TypeCodom <--+------[extract]--------+
/// ```
///
/// # Builder methods
///
/// [`Uncomputed`] provides multiple ways to create solutions:
/// - [`new`](Uncomputed::new) - From explicit values
/// - [`default`](Uncomputed::default) - Placeholder with zero/default values
/// - [`default_vec`](Uncomputed::default_vec) - Batch of placeholders
pub trait Uncomputed<SolId, Dom, SInfo>
where
    Self: Solution<SolId, Dom, SInfo> + IntoComputed,
    SolId: Id,
    Dom: Domain,
    SInfo: SolInfo,
{
    /// The uncomputed twin type in an alternative domain.
    ///
    /// Unlike [`Twin`](Solution::Twin), this always produces an [`Uncomputed`] solution,
    /// preserving the uncomputed status across domain transformations.
    type TwinUC<B: Domain>: Uncomputed<SolId, B, SInfo, Twin<Dom> = Self, TwinUC<Dom> = Self>;

    /// Creates an uncomputed twin solution in a different domain.
    ///
    /// # Type Parameters
    ///
    /// * `B` - The target domain
    ///
    /// # Parameters
    ///
    /// * `x` - Variable values in the target domain
    ///
    /// # Returns
    ///
    /// An uncomputed solution in domain `B` with the same [`Id`] as `self`.
    fn twin<B: Domain>(
        &self,
        x: <Self::TwinUC<B> as Solution<SolId, B, SInfo>>::Raw,
    ) -> Self::TwinUC<B>;

    /// Creates a new uncomputed solution with specified values.
    ///
    /// # Parameters
    ///
    /// * `id` - Unique identifier for this solution
    /// * `x` - Variable values (convertible to [`Raw`](Solution::Raw))
    /// * `info` - Solution metadata
    ///
    /// # Returns
    ///
    /// A new uncomputed solution.
    fn new<T>(id: SolId, x: T, info: Arc<SInfo>) -> Self
    where
        T: Into<Self::Raw>;

    /// Creates a placeholder uncomputed solution with default/zero values.
    ///
    /// Useful for initializing data structures before filling them with actual solutions.
    ///
    /// # Parameters
    ///
    /// * `info` - Solution metadata
    /// * `size` - Number of variables (dimension)
    ///
    /// # Returns
    ///
    /// An uncomputed solution with default values.
    fn default(info: Arc<SInfo>, size: usize) -> Self;

    /// Creates a vector of placeholder uncomputed solutions.
    ///
    /// Batch version of [`default`](Uncomputed::default) for initializing collections.
    ///
    /// # Parameters
    ///
    /// * `info` - Shared solution metadata
    /// * `size` - Number of variables per solution (dimension)
    /// * `vsize` - Number of solutions to create
    ///
    /// # Returns
    ///
    /// A vector of `vsize` uncomputed solutions, each with `size` default values.
    fn default_vec(info: Arc<SInfo>, size: usize, vsize: usize) -> Vec<Self>;
}

/// Trait for converting uncomputed solutions to computed solutions with objective values.
///
/// [`IntoComputed`] enables the transformation from unevaluated solutions to evaluated ones
/// by associating an objective function output ([`TypeCodom`](Codomain::TypeCodom)). This trait
/// also provides the reverse operation to extract the original solution and its value.
///
/// # Usage
///
/// ```text
/// Uncomputed --[into_computed]--> Computed
///                                     |
///                                     v
///                            (Uncomputed, Y) --[extract]
/// ```
///
/// # Type-Level Design
///
/// The [`Computed`](IntoComputed::Computed) associated type is generic over the codomain,
/// allowing a single uncomputed solution to be converted into computed forms with different
/// outcome types (single-objective, multi-objective, constrained, etc.).
pub trait IntoComputed: Sized {
    /// The computed type wrapping `Self` with an objective value.
    ///
    /// This type must implement [`HasY`] to provide access to the objective function output.
    type Computed<Out: Outcome>: HasY<Out> + Serialize + for<'a> Deserialize<'a> + Debug;

    /// Converts this uncomputed solution into a computed one with an objective value.
    ///
    /// # Type Parameters
    ///
    /// * `Cod` - The [`Codomain`] defining the output structure
    /// * `Out` - The outcome type from the objective function
    ///
    /// # Parameters
    ///
    /// * `y` - The objective function output to associate with this solution
    ///
    /// # Returns
    ///
    /// A computed solution containing both `self` and `y`.
    fn into_computed<Out: Outcome>(self, y: Arc<TypeCodom<Out>>) -> Self::Computed<Out>;

    /// Extracts the uncomputed solution and objective value from a computed solution.
    ///
    /// This is the inverse operation of [`into_computed`](IntoComputed::into_computed),
    /// decomposing a computed solution back into its constituent parts.
    ///
    /// # Type Parameters
    ///
    /// * `Cod` - The [`Codomain`] of the objective value
    /// * `Out` - The [`Outcome`] type
    ///
    /// # Parameters
    ///
    /// * `comp` - The computed solution to decompose
    ///
    /// # Returns
    ///
    /// A tuple of `(uncomputed_solution, objective_value)`.
    fn extract<Out: Outcome>(comp: Self::Computed<Out>) -> (Self, Arc<TypeCodom<Out>>);
}

pub trait IntoComputedShape<SolId, SInfo>: SolutionShape<SolId, SInfo>
where
    SolId: Id,
    SInfo: SolInfo,
    Self::SolObj: Uncomputed<SolId, Self::Obj, SInfo> + IntoComputed,
    Self::SolOpt: Uncomputed<SolId, Self::Opt, SInfo> + IntoComputed,
{
    /// The computed type wrapping `Self` with an objective value.
    ///
    /// This type must implement [`HasY`] to provide access to the objective function output.
    type Computed<Out: Outcome>: SolutionShape<
            SolId,
            SInfo,
            Obj = Self::Obj,
            Opt = Self::Opt,
            SolObj = Computed<Self::SolObj, SolId, Self::Obj, Out, SInfo>,
            SolOpt = Computed<Self::SolOpt, SolId, Self::Opt, Out, SInfo>,
        > + HasY<Out>
        + Serialize
        + for<'a> Deserialize<'a>
        + Debug;

    /// Converts this uncomputed solution into a computed one with an objective value.
    ///
    /// # Type Parameters
    ///
    /// * `Cod` - The [`Codomain`] defining the output structure
    /// * `Out` - The outcome type from the objective function
    ///
    /// # Parameters
    ///
    /// * `y` - The objective function output to associate with this solution
    ///
    /// # Returns
    ///
    /// A computed solution containing both `self` and `y`.
    fn into_computed<Out: Outcome>(self, y: Arc<TypeCodom<Out>>) -> Self::Computed<Out>;

    /// Extracts the uncomputed solution and objective value from a computed solution.
    ///
    /// This is the inverse operation of [`into_computed`](IntoComputed::into_computed),
    /// decomposing a computed solution back into its constituent parts.
    ///
    /// # Type Parameters
    ///
    /// * `Cod` - The [`Codomain`] of the objective value
    /// * `Out` - The [`Outcome`] type
    ///
    /// # Parameters
    ///
    /// * `comp` - The computed solution to decompose
    ///
    /// # Returns
    ///
    /// A tuple of `(uncomputed_solution, objective_value)`.
    fn extract<Out: Outcome>(comp: Self::Computed<Out>) -> (Self, Arc<TypeCodom<Out>>);
}

/// Type alias for the twin solution type in an alternative domain.
///
/// [`SolTwin`] extracts the [`Twin`](Solution::Twin) associated type from a solution,
/// providing a convenient way to refer to the solution type in domain `B` that is
/// twin to a solution of type `S` in domain `A`.
pub type SolTwin<S, SolId, A, B, SInfo> = <S as Solution<SolId, A, SInfo>>::Twin<B>;

/// Type alias for the raw value type of a solution.
///
/// [`SolRaw`] extracts the [`Raw`](Solution::Raw) associated type from a solution,
/// providing the native type used to represent variable values in the given domain.
pub type SolRaw<S, SolId, Dom, Info> = <S as Solution<SolId, Dom, Info>>::Raw;

pub mod id;
pub use id::{Id, ParSId, SId, StepId, StepSId};

pub mod partial;
pub use partial::{BaseSol, Fidelity, FidelitySol};

pub mod computed;
pub use computed::{Computed, Xy};

pub mod batchtype;
pub use batchtype::{Batch, OutBatch};

pub mod shape;
pub use shape::{CompLone, Lone, Pair, SolutionShape};