SolutionEvaluation.cs

Go to the documentation of this file.

using System;
using System.Xml.Serialization;
using LotSizingDataModel.Core.Common;
using LotSizingDataModel.Solution.Common;
 
namespace LotSizingDataModel.Solution.Evaluation;
 
/// <summary>
/// Describes the independent evaluation of a
/// lot-sizing solution candidate.
/// </summary>
/// <remarks>
/// A solution may be generated by one method and evaluated
/// by another component. For example, a heuristic solution
/// may be checked by an independent feasibility validator
/// and evaluated by a cost calculator.
/// </remarks>
[Serializable]
[XmlType(TypeName = "solutionEvaluation")]
public sealed class SolutionEvaluation : ModelObject
{
    private FeasibilityStatus _feasibilityStatus =
        FeasibilityStatus.NotEvaluated;
 
    private OptimalityStatus _optimalityStatus =
        OptimalityStatus.NotEvaluated;
 
    private DateTime _evaluatedAtUtc =
        DateTime.UtcNow;
 
    private string _evaluatorName =
        string.Empty;
 
    private string _evaluatorVersion =
        string.Empty;
 
    private string _objectiveValueSource =
        string.Empty;
 
    private string _comment =
        string.Empty;
 
    private double? _objectiveValue;
    private double? _bestBound;
    private double? _absoluteGap;
    private double? _relativeGap;
 
    private double? _maximumConstraintViolation;
    private double? _totalConstraintViolation;
 
    private int? _violatedConstraintCount;
 
    /// <summary>
    /// Initializes an empty solution evaluation.
    /// </summary>
    /// <remarks>
    /// The evaluation date is initialized with the current
    /// Coordinated Universal Time.
    /// </remarks>
    public SolutionEvaluation()
    {
    }
 
    /// <summary>
    /// Initializes a solution evaluation with feasibility
    /// and optimality information.
    /// </summary>
    /// <param name="feasibilityStatus">
    /// Evaluated feasibility status of the solution.
    /// </param>
    /// <param name="optimalityStatus">
    /// Available information about solution optimality.
    /// </param>
    public SolutionEvaluation(
        FeasibilityStatus feasibilityStatus,
        OptimalityStatus optimalityStatus)
        : this()
    {
        FeasibilityStatus = feasibilityStatus;
        OptimalityStatus = optimalityStatus;
    }
 
    /// <summary>
    /// Gets or sets the evaluated feasibility status
    /// of the solution.
    /// </summary>
    [XmlAttribute("feasibilityStatus")]
    public FeasibilityStatus FeasibilityStatus
    {
        get => _feasibilityStatus;
        set => SetProperty(
            ref _feasibilityStatus,
            value);
    }
 
    /// <summary>
    /// Gets or sets the available information about
    /// the optimality of the solution.
    /// </summary>
    [XmlAttribute("optimalityStatus")]
    public OptimalityStatus OptimalityStatus
    {
        get => _optimalityStatus;
        set => SetProperty(
            ref _optimalityStatus,
            value);
    }
 
    /// <summary>
    /// Gets or sets the UTC date and time at which
    /// the evaluation was performed.
    /// </summary>
    [XmlElement("evaluatedAtUtc")]
    public DateTime EvaluatedAtUtc
    {
        get => _evaluatedAtUtc;
        set
        {
            DateTime utcValue =
                value.Kind switch
                {
                    DateTimeKind.Utc =>
                        value,
 
                    DateTimeKind.Local =>
                        value.ToUniversalTime(),
 
                    _ =>
                        DateTime.SpecifyKind(
                            value,
                            DateTimeKind.Utc)
                };
 
            SetProperty(
                ref _evaluatedAtUtc,
                utcValue);
        }
    }
 
    /// <summary>
    /// Gets or sets the name of the component
    /// that evaluated the solution.
    /// </summary>
    /// <example>
    /// LotSizingSolutionEvaluator, IBM ILOG CPLEX
    /// or Independent feasibility checker.
    /// </example>
    [XmlAttribute("evaluatorName")]
    public string EvaluatorName
    {
        get => _evaluatorName;
        set => SetProperty(
            ref _evaluatorName,
            value?.Trim() ?? string.Empty);
    }
 
    /// <summary>
    /// Gets or sets the version of the component
    /// that evaluated the solution.
    /// </summary>
    [XmlAttribute("evaluatorVersion")]
    public string EvaluatorVersion
    {
        get => _evaluatorVersion;
        set => SetProperty(
            ref _evaluatorVersion,
            value?.Trim() ?? string.Empty);
    }
 
    /// <summary>
    /// Gets or sets a description of the source
    /// of the recorded objective value.
    /// </summary>
    /// <example>
    /// CostAnalyzer, CPLEX incumbent value
    /// or imported benchmark value.
    /// </example>
    [XmlAttribute("objectiveValueSource")]
    public string ObjectiveValueSource
    {
        get => _objectiveValueSource;
        set => SetProperty(
            ref _objectiveValueSource,
            value?.Trim() ?? string.Empty);
    }
 
    /// <summary>
    /// Gets or sets the evaluated objective value.
    /// </summary>
    /// <remarks>
    /// A null value means that no objective value
    /// has been calculated or recorded.
    /// </remarks>
    [XmlElement("objectiveValue", IsNullable = true)]
    public double? ObjectiveValue
    {
        get => _objectiveValue;
        set
        {
            ValidateNullableFiniteValue(
                value,
                nameof(value));
 
            if (SetProperty(
                    ref _objectiveValue,
                    value))
            {
                OnPropertyChanged(
                    nameof(HasObjectiveValue));
            }
        }
    }
 
    /// <summary>
    /// Gets or sets a valid bound on the optimal
    /// objective value.
    /// </summary>
    /// <remarks>
    /// For a minimization problem, this is normally a lower
    /// bound. For a maximization problem, it is normally
    /// an upper bound. A null value means that no bound
    /// is available.
    /// </remarks>
    [XmlElement("bestBound", IsNullable = true)]
    public double? BestBound
    {
        get => _bestBound;
        set
        {
            ValidateNullableFiniteValue(
                value,
                nameof(value));
 
            if (SetProperty(
                    ref _bestBound,
                    value))
            {
                OnPropertyChanged(
                    nameof(HasBestBound));
            }
        }
    }
 
    /// <summary>
    /// Gets or sets the absolute optimality gap.
    /// </summary>
    /// <remarks>
    /// A null value means that no absolute gap
    /// has been calculated.
    /// </remarks>
    [XmlElement("absoluteGap", IsNullable = true)]
    public double? AbsoluteGap
    {
        get => _absoluteGap;
        set
        {
            ValidateNullableNonNegativeFiniteValue(
                value,
                nameof(value));
 
            SetProperty(
                ref _absoluteGap,
                value);
        }
    }
 
    /// <summary>
    /// Gets or sets the relative optimality gap.
    /// </summary>
    /// <remarks>
    /// The value is stored as a ratio. For example,
    /// 0.01 represents a relative gap of one percent.
    /// A null value means that no relative gap
    /// has been calculated.
    /// </remarks>
    [XmlElement("relativeGap", IsNullable = true)]
    public double? RelativeGap
    {
        get => _relativeGap;
        set
        {
            ValidateNullableNonNegativeFiniteValue(
                value,
                nameof(value));
 
            SetProperty(
                ref _relativeGap,
                value);
        }
    }
 
    /// <summary>
    /// Gets or sets the largest absolute constraint
    /// violation detected in the solution.
    /// </summary>
    /// <remarks>
    /// A null value means that this measure
    /// has not been calculated.
    /// </remarks>
    [XmlElement(
        "maximumConstraintViolation",
        IsNullable = true)]
    public double? MaximumConstraintViolation
    {
        get => _maximumConstraintViolation;
        set
        {
            ValidateNullableNonNegativeFiniteValue(
                value,
                nameof(value));
 
            if (SetProperty(
                    ref _maximumConstraintViolation,
                    value))
            {
                OnPropertyChanged(
                    nameof(HasConstraintViolationMetrics));
            }
        }
    }
 
    /// <summary>
    /// Gets or sets the sum of the absolute
    /// constraint violations detected in the solution.
    /// </summary>
    /// <remarks>
    /// A null value means that this measure
    /// has not been calculated.
    /// </remarks>
    [XmlElement(
        "totalConstraintViolation",
        IsNullable = true)]
    public double? TotalConstraintViolation
    {
        get => _totalConstraintViolation;
        set
        {
            ValidateNullableNonNegativeFiniteValue(
                value,
                nameof(value));
 
            if (SetProperty(
                    ref _totalConstraintViolation,
                    value))
            {
                OnPropertyChanged(
                    nameof(HasConstraintViolationMetrics));
            }
        }
    }
 
    /// <summary>
    /// Gets or sets the number of violated constraints.
    /// </summary>
    /// <remarks>
    /// A null value means that the number of violations
    /// has not been calculated.
    /// </remarks>
    [XmlElement(
        "violatedConstraintCount",
        IsNullable = true)]
    public int? ViolatedConstraintCount
    {
        get => _violatedConstraintCount;
        set
        {
            if (value.HasValue &&
                value.Value < 0)
            {
                throw new ArgumentOutOfRangeException(
                    nameof(value),
                    value,
                    "The violated-constraint count " +
                    "cannot be negative.");
            }
 
            if (SetProperty(
                    ref _violatedConstraintCount,
                    value))
            {
                OnPropertyChanged(
                    nameof(HasConstraintViolationMetrics));
            }
        }
    }
 
    /// <summary>
    /// Gets or sets an optional human-readable comment
    /// about the evaluation.
    /// </summary>
    [XmlElement("comment")]
    public string Comment
    {
        get => _comment;
        set => SetProperty(
            ref _comment,
            value ?? string.Empty);
    }
 
    /// <summary>
    /// Gets a value indicating whether an objective
    /// value has been recorded.
    /// </summary>
    [XmlIgnore]
    public bool HasObjectiveValue =>
        ObjectiveValue.HasValue;
 
    /// <summary>
    /// Gets a value indicating whether a valid
    /// objective bound has been recorded.
    /// </summary>
    [XmlIgnore]
    public bool HasBestBound =>
        BestBound.HasValue;
 
    /// <summary>
    /// Gets a value indicating whether at least one
    /// constraint-violation metric has been recorded.
    /// </summary>
    [XmlIgnore]
    public bool HasConstraintViolationMetrics =>
        MaximumConstraintViolation.HasValue ||
        TotalConstraintViolation.HasValue ||
        ViolatedConstraintCount.HasValue;
 
    /// <summary>
    /// Records the objective value and its source.
    /// </summary>
    /// <param name="objectiveValue">
    /// Finite objective value.
    /// </param>
    /// <param name="source">
    /// Optional description of the objective-value source.
    /// </param>
    public void SetObjectiveValue(
        double objectiveValue,
        string source = "")
    {
        ObjectiveValue = objectiveValue;
        ObjectiveValueSource = source;
    }
 
    /// <summary>
    /// Records bound and optimality-gap information.
    /// </summary>
    /// <param name="bestBound">
    /// Finite bound on the optimal objective value.
    /// </param>
    /// <param name="absoluteGap">
    /// Non-negative absolute optimality gap.
    /// </param>
    /// <param name="relativeGap">
    /// Non-negative relative optimality gap expressed
    /// as a ratio.
    /// </param>
    public void SetOptimalityInformation(
        double bestBound,
        double absoluteGap,
        double relativeGap)
    {
        BestBound = bestBound;
        AbsoluteGap = absoluteGap;
        RelativeGap = relativeGap;
    }
 
    /// <summary>
    /// Records constraint-violation metrics.
    /// </summary>
    /// <param name="maximumViolation">
    /// Largest non-negative absolute constraint violation.
    /// </param>
    /// <param name="totalViolation">
    /// Sum of non-negative absolute constraint violations.
    /// </param>
    /// <param name="violatedConstraintCount">
    /// Number of violated constraints.
    /// </param>
    public void SetConstraintViolationMetrics(
        double maximumViolation,
        double totalViolation,
        int violatedConstraintCount)
    {
        if (maximumViolation > totalViolation)
        {
            throw new ArgumentException(
                "The maximum constraint violation cannot " +
                "exceed the total constraint violation.",
                nameof(maximumViolation));
        }
 
        MaximumConstraintViolation =
            maximumViolation;
 
        TotalConstraintViolation =
            totalViolation;
 
        ViolatedConstraintCount =
            violatedConstraintCount;
    }
 
    /// <summary>
    /// Removes all recorded quantitative
    /// optimality information.
    /// </summary>
    public void ClearOptimalityInformation()
    {
        BestBound = null;
        AbsoluteGap = null;
        RelativeGap = null;
    }
 
    /// <summary>
    /// Removes all recorded constraint-violation metrics.
    /// </summary>
    public void ClearConstraintViolationMetrics()
    {
        MaximumConstraintViolation = null;
        TotalConstraintViolation = null;
        ViolatedConstraintCount = null;
    }
 
    /// <inheritdoc/>
    public override string ToString()
    {
        string objectiveDescription =
            ObjectiveValue.HasValue
                ? ObjectiveValue.Value.ToString(
                    System.Globalization.CultureInfo
                        .InvariantCulture)
                : "not evaluated";
 
        return
            $"Feasibility: {FeasibilityStatus}; " +
            $"optimality: {OptimalityStatus}; " +
            $"objective: {objectiveDescription}";
    }
 
    private static void ValidateNullableFiniteValue(
        double? value,
        string parameterName)
    {
        if (value.HasValue &&
            !double.IsFinite(value.Value))
        {
            throw new ArgumentOutOfRangeException(
                parameterName,
                value,
                "The value must be finite.");
        }
    }
 
    private static void
        ValidateNullableNonNegativeFiniteValue(
            double? value,
            string parameterName)
    {
        if (value.HasValue &&
            (!double.IsFinite(value.Value) ||
             value.Value < 0.0))
        {
            throw new ArgumentOutOfRangeException(
                parameterName,
                value,
                "The value must be finite and non-negative.");
        }
    }
}