ResourceLoadAnalyzer.cs

Go to the documentation of this file.

using System;
using System.Collections.Generic;
using System.Linq;
using LotSizingDataModel.Core.Indexing;
using LotSizingDataModel.Core.PhysicalModel;
using LotSizingDataModel.Core.Querying;
using LotSizingDataModel.Core.Relationships;
 
namespace LotSizingDataModel.Core.Analysis;
 
/// <summary>
/// Aggregates the capacity loads generated by several items
/// using the same resource during one planning period.
///
/// The analyzer supports:
/// - production work centers;
/// - warehouses;
/// - transport resources.
///
/// It does not modify the supply-chain model.
/// </summary>
public sealed class ResourceLoadAnalyzer
{
    /// <summary>
    /// Initializes a resource-load analyzer and creates
    /// a new supply-chain index.
    /// </summary>
    public ResourceLoadAnalyzer(SupplyChain supplyChain)
        : this(
            new SupplyChainIndex(
                supplyChain ??
                throw new ArgumentNullException(
                    nameof(supplyChain))))
    {
    }
 
    /// <summary>
    /// Initializes a resource-load analyzer using
    /// an existing supply-chain index.
    /// </summary>
    public ResourceLoadAnalyzer(SupplyChainIndex index)
    {
        Index = index ??
            throw new ArgumentNullException(nameof(index));
 
        SupplyChain = index.SupplyChain;
        Queries = new SupplyChainQueries(index);
    }
 
    /// <summary>
    /// Gets the analyzed supply chain.
    /// </summary>
    public SupplyChain SupplyChain { get; }
 
    /// <summary>
    /// Gets the entity index used by the analyzer.
    /// </summary>
    public SupplyChainIndex Index { get; }
 
    /// <summary>
    /// Gets the query service used to resolve relationships.
    /// </summary>
    public SupplyChainQueries Queries { get; }
 
    /// <summary>
    /// Rebuilds the underlying entity index.
    ///
    /// Call this method after directly changing entity
    /// collections in the supply chain.
    /// </summary>
    public void RebuildIndex()
    {
        Index.Rebuild();
    }
 
    #region Production load
 
    /// <summary>
    /// Aggregates the production loads generated by several
    /// items on the same work center during one period.
    ///
    /// Several entries referring to the same item are combined.
    /// Their quantities are summed and setup is counted once
    /// when at least one entry activates it.
    /// </summary>
    public ResourceLoadReport AnalyzeWorkCenterLoad(
        WorkCenterReference workCenterReference,
        int period,
        IEnumerable<ItemResourceActivity> activities)
    {
        ArgumentNullException.ThrowIfNull(
            workCenterReference);
 
        ValidatePeriod(period);
 
        WorkCenter workCenter =
            Index.GetRequiredWorkCenter(
                workCenterReference);
 
        IReadOnlyList<NormalizedActivity>
            normalizedActivities =
                NormalizeActivities(activities);
 
        var itemLoads =
            new List<ItemLoadResult>(
                normalizedActivities.Count);
 
        foreach (NormalizedActivity activity
                 in normalizedActivities)
        {
            ProductionCharacteristic characteristic =
                Queries.GetRequiredProductionCharacteristic(
                    activity.ItemId,
                    workCenterReference);
 
            double unitCapacity =
                characteristic.UnitCapacityConsumption
                    ?.GetConsumption(period) ??
                0.0;
 
            double setupCapacity =
                activity.SetupActivated
                    ? characteristic.SetupTime
                          ?.GetSetupTime(period) ??
                      0.0
                    : 0.0;
 
            itemLoads.Add(
                CreateItemLoad(
                    activity,
                    unitCapacity,
                    setupCapacity,
                    itemSpecificRegularCapacity: null,
                    itemSpecificAdditionalCapacity: null));
        }
 
        return CreateReport(
            ResourceLoadKind.Production,
            resourceKey:
                $"{workCenterReference.PlantId}:" +
                $"{workCenterReference.WorkCenterId}",
            resourceName: workCenter.Name,
            period,
            itemLoads,
            globalRegularCapacity:
                workCenter.CapacityConstraint
                    ?.GetMaximumCapacity(period),
            globalAdditionalCapacity:
                workCenter.AdditionalCapacity
                    ?.GetMaximumAdditionalCapacity(period));
    }
 
    #endregion
 
    #region Warehouse load
 
    /// <summary>
    /// Aggregates the storage loads generated by several items
    /// in the same warehouse during one period.
    ///
    /// The quantity of an activity represents the inventory
    /// level of the corresponding item during the period.
    /// </summary>
    public ResourceLoadReport AnalyzeWarehouseLoad(
        WarehouseReference warehouseReference,
        int period,
        IEnumerable<ItemResourceActivity> activities)
    {
        ArgumentNullException.ThrowIfNull(
            warehouseReference);
 
        ValidatePeriod(period);
 
        Warehouse warehouse =
            Index.GetRequiredWarehouse(
                warehouseReference);
 
        IReadOnlyList<NormalizedActivity>
            normalizedActivities =
                NormalizeActivities(activities);
 
        var itemLoads =
            new List<ItemLoadResult>(
                normalizedActivities.Count);
 
        foreach (NormalizedActivity activity
                 in normalizedActivities)
        {
            Inventory inventory =
                Queries.GetRequiredInventory(
                    activity.ItemId,
                    warehouseReference);
 
            double unitCapacity =
                inventory.UnitCapacityConsumption
                    ?.GetConsumption(period) ??
                0.0;
 
            double setupCapacity =
                activity.SetupActivated
                    ? inventory.SetupTime
                          ?.GetSetupTime(period) ??
                      0.0
                    : 0.0;
 
            itemLoads.Add(
                CreateItemLoad(
                    activity,
                    unitCapacity,
                    setupCapacity,
                    itemSpecificRegularCapacity:
                        inventory.CapacityConstraint
                            ?.GetMaximumCapacity(period),
                    itemSpecificAdditionalCapacity:
                        inventory.AdditionalCapacity
                            ?.GetMaximumAdditionalCapacity(
                                period)));
        }
 
        return CreateReport(
            ResourceLoadKind.Storage,
            resourceKey:
                $"{warehouseReference.Kind}:" +
                $"{warehouseReference.ReferenceId}",
            resourceName: warehouse.Name,
            period,
            itemLoads,
            globalRegularCapacity:
                warehouse.CapacityConstraint
                    ?.GetMaximumCapacity(period),
            globalAdditionalCapacity:
                warehouse.AdditionalCapacity
                    ?.GetMaximumAdditionalCapacity(period));
    }
 
    #endregion
 
    #region Transport load
 
    /// <summary>
    /// Aggregates the transport loads generated by several items
    /// using the same transport resource during one period.
    ///
    /// The quantity of an activity must represent the total
    /// quantity transported by the resource for the item during
    /// the period, over all its transport lanes.
    /// </summary>
    public ResourceLoadReport AnalyzeTransportResourceLoad(
        int transportResourceId,
        int period,
        IEnumerable<ItemResourceActivity> activities)
    {
        ValidatePeriod(period);
 
        TransportResource resource =
            Index.GetRequiredTransportResource(
                transportResourceId);
 
        IReadOnlyList<NormalizedActivity>
            normalizedActivities =
                NormalizeActivities(activities);
 
        var itemLoads =
            new List<ItemLoadResult>(
                normalizedActivities.Count);
 
        foreach (NormalizedActivity activity
                 in normalizedActivities)
        {
            TransportCharacteristic characteristic =
                Queries.GetRequiredTransportCharacteristic(
                    activity.ItemId,
                    transportResourceId);
 
            double unitCapacity =
                characteristic.UnitCapacityConsumption
                    ?.GetConsumption(period) ??
                0.0;
 
            double setupCapacity =
                activity.SetupActivated
                    ? characteristic.SetupTime
                          ?.GetSetupTime(period) ??
                      0.0
                    : 0.0;
 
            itemLoads.Add(
                CreateItemLoad(
                    activity,
                    unitCapacity,
                    setupCapacity,
                    itemSpecificRegularCapacity:
                        characteristic.CapacityConstraint
                            ?.GetMaximumCapacity(period),
                    itemSpecificAdditionalCapacity:
                        characteristic.AdditionalCapacity
                            ?.GetMaximumAdditionalCapacity(
                                period)));
        }
 
        return CreateReport(
            ResourceLoadKind.Transport,
            resourceKey: transportResourceId.ToString(),
            resourceName: resource.Name,
            period,
            itemLoads,
            globalRegularCapacity:
                resource.CapacityConstraint
                    ?.GetMaximumCapacity(period),
            globalAdditionalCapacity:
                resource.AdditionalCapacity
                    ?.GetMaximumAdditionalCapacity(period));
    }
 
    #endregion
 
    #region Private calculations
 
    private ResourceLoadReport CreateReport(
        ResourceLoadKind resourceKind,
        string resourceKey,
        string resourceName,
        int period,
        IEnumerable<ItemLoadResult> itemLoads,
        double? globalRegularCapacity,
        double? globalAdditionalCapacity)
    {
        ValidateOptionalCapacityConfiguration(
            globalRegularCapacity,
            globalAdditionalCapacity,
            "global resource capacity");
 
        return new ResourceLoadReport(
            resourceKind,
            resourceKey,
            resourceName,
            period,
            itemLoads,
            globalRegularCapacity,
            globalAdditionalCapacity);
    }
 
    private static ItemLoadResult CreateItemLoad(
        NormalizedActivity activity,
        double unitCapacity,
        double setupCapacity,
        double? itemSpecificRegularCapacity,
        double? itemSpecificAdditionalCapacity)
    {
        ValidateNonNegativeFiniteValue(
            unitCapacity,
            nameof(unitCapacity));
 
        ValidateNonNegativeFiniteValue(
            setupCapacity,
            nameof(setupCapacity));
 
        ValidateOptionalCapacityConfiguration(
            itemSpecificRegularCapacity,
            itemSpecificAdditionalCapacity,
            "item-specific capacity");
 
        double quantityCapacity =
            activity.Quantity * unitCapacity;
 
        if (!double.IsFinite(quantityCapacity))
        {
            throw new InvalidOperationException(
                "The calculated unit-capacity requirement " +
                "exceeds the supported numerical range.");
        }
 
        double requiredCapacity =
            quantityCapacity + setupCapacity;
 
        if (!double.IsFinite(requiredCapacity))
        {
            throw new InvalidOperationException(
                "The calculated resource load exceeds the " +
                "supported numerical range.");
        }
 
        return new ItemLoadResult(
            activity.ItemId,
            activity.Quantity,
            activity.SetupActivated,
            unitCapacity,
            setupCapacity,
            requiredCapacity,
            itemSpecificRegularCapacity,
            itemSpecificAdditionalCapacity);
    }
 
    private IReadOnlyList<NormalizedActivity>
        NormalizeActivities(
            IEnumerable<ItemResourceActivity> activities)
    {
        ArgumentNullException.ThrowIfNull(activities);
 
        var normalized =
            new Dictionary<int, NormalizedActivity>();
 
        foreach (ItemResourceActivity activity
                 in activities)
        {
            if (activity is null)
            {
                throw new ArgumentException(
                    "The activity collection cannot contain null.",
                    nameof(activities));
            }
 
            Index.GetRequiredItem(activity.ItemId);
 
            ValidateNonNegativeFiniteValue(
                activity.Quantity,
                nameof(activity.Quantity));
 
            if (!normalized.TryGetValue(
                    activity.ItemId,
                    out NormalizedActivity? existing))
            {
                normalized.Add(
                    activity.ItemId,
                    new NormalizedActivity(
                        activity.ItemId,
                        activity.Quantity,
                        activity.SetupActivated));
 
                continue;
            }
 
            double totalQuantity =
                existing.Quantity +
                activity.Quantity;
 
            if (!double.IsFinite(totalQuantity))
            {
                throw new InvalidOperationException(
                    $"The aggregated quantity for item " +
                    $"{activity.ItemId} exceeds the supported " +
                    "numerical range.");
            }
 
            normalized[activity.ItemId] =
                new NormalizedActivity(
                    activity.ItemId,
                    totalQuantity,
                    existing.SetupActivated ||
                    activity.SetupActivated);
        }
 
        return normalized.Values
            .OrderBy(activity => activity.ItemId)
            .ToArray();
    }
 
    private void ValidatePeriod(int period)
    {
        if (period < 1 ||
            period > SupplyChain.PlanningHorizon)
        {
            throw new ArgumentOutOfRangeException(
                nameof(period),
                period,
                $"The period must be between 1 and " +
                $"{SupplyChain.PlanningHorizon}.");
        }
    }
 
    private static void
        ValidateOptionalCapacityConfiguration(
            double? regularCapacity,
            double? additionalCapacity,
            string capacityName)
    {
        if (regularCapacity.HasValue)
        {
            ValidateNonNegativeFiniteValue(
                regularCapacity.Value,
                nameof(regularCapacity));
        }
 
        if (additionalCapacity.HasValue)
        {
            ValidateNonNegativeFiniteValue(
                additionalCapacity.Value,
                nameof(additionalCapacity));
 
            if (!regularCapacity.HasValue)
            {
                throw new InvalidOperationException(
                    $"The {capacityName} defines additional " +
                    "capacity without regular capacity.");
            }
        }
    }
 
    private static void ValidateNonNegativeFiniteValue(
        double value,
        string parameterName)
    {
        if (!double.IsFinite(value) ||
            value < 0.0)
        {
            throw new ArgumentOutOfRangeException(
                parameterName,
                value,
                "The value must be finite and non-negative.");
        }
    }
 
    #endregion
 
    /// <summary>
    /// Identifies the type of resource represented
    /// by a load report.
    /// </summary>
    public enum ResourceLoadKind
    {
        /// <summary>
        /// Production resource such as a work center.
        /// </summary>
        Production,
 
        /// <summary>
        /// Storage resource such as a warehouse.
        /// </summary>
        Storage,
 
        /// <summary>
        /// Transport resource.
        /// </summary>
        Transport
    }
 
    /// <summary>
    /// Represents the activity of one item on a resource
    /// during one planning period.
    /// </summary>
    public sealed class ItemResourceActivity
    {
        /// <summary>
        /// Initializes an item-resource activity.
        /// </summary>
        /// <param name="itemId">
        /// Identifier of the processed item.
        /// </param>
        /// <param name="quantity">
        /// Non-negative finite quantity processed, stored
        /// or transported during the period.
        /// </param>
        /// <param name="setupActivated">
        /// Indicates whether the setup capacity must be included.
        /// </param>
        public ItemResourceActivity(
            int itemId,
            double quantity,
            bool setupActivated)
        {
            if (itemId <= 0)
            {
                throw new ArgumentOutOfRangeException(
                    nameof(itemId),
                    itemId,
                    "The item identifier must be strictly positive.");
            }
 
            ValidateNonNegativeFiniteValue(
                quantity,
                nameof(quantity));
 
            ItemId = itemId;
            Quantity = quantity;
            SetupActivated = setupActivated;
        }
 
        /// <summary>
        /// Gets the item identifier.
        /// </summary>
        public int ItemId { get; }
 
        /// <summary>
        /// Gets the processed, stored or transported quantity.
        /// </summary>
        public double Quantity { get; }
 
        /// <summary>
        /// Gets a value indicating whether setup is activated.
        /// </summary>
        public bool SetupActivated { get; }
    }
 
    /// <summary>
    /// Internal activity obtained after grouping all entries
    /// referring to the same item.
    /// </summary>
    private sealed class NormalizedActivity
    {
        public NormalizedActivity(
            int itemId,
            double quantity,
            bool setupActivated)
        {
            ItemId = itemId;
            Quantity = quantity;
            SetupActivated = setupActivated;
        }
 
        public int ItemId { get; }
 
        public double Quantity { get; }
 
        public bool SetupActivated { get; }
    }
 
    /// <summary>
    /// Represents the load generated by one item on a resource.
    /// </summary>
    public sealed class ItemLoadResult
    {
        /// <summary>
        /// Initializes the capacity-load result of one item
        /// on a resource during one planning period.
        /// </summary>
        /// <param name="itemId">
        /// Identifier of the item.
        /// </param>
        /// <param name="quantity">
        /// Quantity processed, stored or transported.
        /// </param>
        /// <param name="setupActivated">
        /// Indicates whether setup is activated.
        /// </param>
        /// <param name="unitCapacity">
        /// Capacity consumed per quantity unit.
        /// </param>
        /// <param name="setupCapacity">
        /// Setup capacity included in the load.
        /// </param>
        /// <param name="requiredCapacity">
        /// Total capacity required by the item.
        /// </param>
        /// <param name="maximumRegularCapacity">
        /// Item-specific regular-capacity limit,
        /// or null when no such limit exists.
        /// </param>
        /// <param name="maximumAdditionalCapacity">
        /// Item-specific additional-capacity limit,
        /// or null when no such limit exists.
        /// </param>
        public ItemLoadResult(
            int itemId,
            double quantity,
            bool setupActivated,
            double unitCapacity,
            double setupCapacity,
            double requiredCapacity,
            double? maximumRegularCapacity,
            double? maximumAdditionalCapacity)
        {
            ValidateNonNegativeFiniteValue(
                quantity,
                nameof(quantity));
 
            ValidateNonNegativeFiniteValue(
                unitCapacity,
                nameof(unitCapacity));
 
            ValidateNonNegativeFiniteValue(
                setupCapacity,
                nameof(setupCapacity));
 
            ValidateNonNegativeFiniteValue(
                requiredCapacity,
                nameof(requiredCapacity));
 
            ValidateOptionalCapacityConfiguration(
                maximumRegularCapacity,
                maximumAdditionalCapacity,
                "item-specific capacity");
 
            ItemId = itemId;
            Quantity = quantity;
            SetupActivated = setupActivated;
            UnitCapacity = unitCapacity;
            SetupCapacity = setupCapacity;
            RequiredCapacity = requiredCapacity;
 
            MaximumRegularCapacity =
                maximumRegularCapacity;
 
            MaximumAdditionalCapacity =
                maximumAdditionalCapacity;
        }
 
        /// <summary>
        /// Gets the item identifier.
        /// </summary>
        public int ItemId { get; }
 
        /// <summary>
        /// Gets the item quantity.
        /// </summary>
        public double Quantity { get; }
 
        /// <summary>
        /// Gets a value indicating whether setup is activated.
        /// </summary>
        public bool SetupActivated { get; }
 
        /// <summary>
        /// Gets the capacity consumed per item unit.
        /// </summary>
        public double UnitCapacity { get; }
 
        /// <summary>
        /// Gets the setup capacity included in the load.
        /// </summary>
        public double SetupCapacity { get; }
 
        /// <summary>
        /// Gets the total capacity required by the item.
        /// </summary>
        public double RequiredCapacity { get; }
 
        /// <summary>
        /// Gets the item-specific regular-capacity limit.
        ///
        /// Null means that no item-specific limit exists.
        /// </summary>
        public double? MaximumRegularCapacity { get; }
 
        /// <summary>
        /// Gets the item-specific additional-capacity limit.
        /// </summary>
        public double? MaximumAdditionalCapacity { get; }
 
        /// <summary>
        /// Gets a value indicating whether an item-specific
        /// capacity constraint exists.
        /// </summary>
        public bool HasItemSpecificCapacity =>
            MaximumRegularCapacity.HasValue;
 
        /// <summary>
        /// Gets the item-specific total maximum capacity.
        /// </summary>
        public double? MaximumTotalCapacity =>
            MaximumRegularCapacity.HasValue
                ? MaximumRegularCapacity.Value +
                  (MaximumAdditionalCapacity ?? 0.0)
                : null;
 
        /// <summary>
        /// Gets the additional capacity required beyond
        /// the regular item-specific capacity.
        /// </summary>
        public double RequiredAdditionalCapacity =>
            MaximumRegularCapacity.HasValue
                ? Math.Max(
                    0.0,
                    RequiredCapacity -
                    MaximumRegularCapacity.Value)
                : 0.0;
 
        /// <summary>
        /// Gets a value indicating whether the item load fits
        /// its regular item-specific capacity.
        /// </summary>
        public bool FitsRegularCapacity =>
            !MaximumRegularCapacity.HasValue ||
            RequiredCapacity <=
                MaximumRegularCapacity.Value;
 
        /// <summary>
        /// Gets a value indicating whether the item load fits
        /// its regular plus additional item-specific capacity.
        /// </summary>
        public bool FitsTotalCapacity =>
            !MaximumTotalCapacity.HasValue ||
            RequiredCapacity <=
                MaximumTotalCapacity.Value;
 
        /// <summary>
        /// Gets the amount exceeding the item-specific
        /// maximum capacity.
        /// </summary>
        public double CapacityExcess =>
            MaximumTotalCapacity.HasValue
                ? Math.Max(
                    0.0,
                    RequiredCapacity -
                    MaximumTotalCapacity.Value)
                : 0.0;
 
        /// <inheritdoc/>
        public override string ToString()
        {
            if (!HasItemSpecificCapacity)
            {
                return
                    $"Item {ItemId}: required " +
                    $"{RequiredCapacity}; no item-specific limit";
            }
 
            return
                $"Item {ItemId}: required {RequiredCapacity}; " +
                $"maximum {MaximumTotalCapacity}; " +
                $"feasible {FitsTotalCapacity}";
        }
    }
 
    /// <summary>
    /// Represents the aggregated load of one resource
    /// during one planning period.
    /// </summary>
    public sealed class ResourceLoadReport
    {
        private readonly ItemLoadResult[] _itemLoads;
        /// <summary>
        /// Initializes a report describing the aggregated load
        /// of a resource during one planning period.
        /// </summary>
        /// <param name="resourceKind">
        /// Type of resource being analyzed: production, storage
        /// or transport.
        /// </param>
        /// <param name="resourceKey">
        /// Technical key uniquely identifying the resource.
        /// </param>
        /// <param name="resourceName">
        /// Human-readable name of the resource.
        /// </param>
        /// <param name="period">
        /// One-based planning period analyzed by the report.
        /// </param>
        /// <param name="itemLoads">
        /// Individual item loads aggregated on the resource.
        /// </param>
        /// <param name="maximumRegularCapacity">
        /// Maximum regular capacity available during the period,
        /// or null when no global regular-capacity constraint exists.
        /// </param>
        /// <param name="maximumAdditionalCapacity">
        /// Maximum additional capacity available during the period,
        /// or null when no global additional capacity is defined.
        /// </param>
        /// <exception cref="ArgumentException">
        /// Thrown when the resource key is empty or invalid.
        /// </exception>
        /// <exception cref="ArgumentNullException">
        /// Thrown when the item-load collection is null.
        /// </exception>
        /// <exception cref="ArgumentOutOfRangeException">
        /// Thrown when the planning period is not strictly positive.
        /// </exception>
        public ResourceLoadReport(
            ResourceLoadKind resourceKind,
            string resourceKey,
            string resourceName,
            int period,
            IEnumerable<ItemLoadResult> itemLoads,
            double? maximumRegularCapacity,
            double? maximumAdditionalCapacity)
        {
            ArgumentException.ThrowIfNullOrWhiteSpace(
                resourceKey);
 
            ArgumentNullException.ThrowIfNull(itemLoads);
 
            if (period <= 0)
            {
                throw new ArgumentOutOfRangeException(
                    nameof(period),
                    period,
                    "The period must be strictly positive.");
            }
 
            ValidateOptionalCapacityConfiguration(
                maximumRegularCapacity,
                maximumAdditionalCapacity,
                "global resource capacity");
 
            ResourceKind = resourceKind;
            ResourceKey = resourceKey;
            ResourceName = resourceName ?? string.Empty;
            Period = period;
 
            _itemLoads = itemLoads
                .OrderBy(load => load.ItemId)
                .ToArray();
 
            MaximumRegularCapacity =
                maximumRegularCapacity;
 
            MaximumAdditionalCapacity =
                maximumAdditionalCapacity;
 
            TotalRequiredCapacity =
                CalculateTotalRequiredCapacity(
                    _itemLoads);
        }
 
        /// <summary>
        /// Gets the resource type.
        /// </summary>
        public ResourceLoadKind ResourceKind { get; }
 
        /// <summary>
        /// Gets the technical resource key.
        /// </summary>
        public string ResourceKey { get; }
 
        /// <summary>
        /// Gets the resource name.
        /// </summary>
        public string ResourceName { get; }
 
        /// <summary>
        /// Gets the analyzed planning period.
        /// </summary>
        public int Period { get; }
 
        /// <summary>
        /// Gets the individual item loads.
        /// </summary>
        public IReadOnlyList<ItemLoadResult> ItemLoads =>
            Array.AsReadOnly(_itemLoads);
 
        /// <summary>
        /// Gets the number of loaded item types.
        /// </summary>
        public int ItemCount => _itemLoads.Length;
 
        /// <summary>
        /// Gets the aggregated required capacity.
        /// </summary>
        public double TotalRequiredCapacity { get; }
 
        /// <summary>
        /// Gets the global regular-capacity limit.
        /// </summary>
        public double? MaximumRegularCapacity { get; }
 
        /// <summary>
        /// Gets the global additional-capacity limit.
        /// </summary>
        public double? MaximumAdditionalCapacity { get; }
 
        /// <summary>
        /// Gets a value indicating whether the resource
        /// has a global capacity constraint.
        /// </summary>
        public bool HasGlobalCapacityConstraint =>
            MaximumRegularCapacity.HasValue;
 
        /// <summary>
        /// Gets the global total maximum capacity.
        /// </summary>
        public double? MaximumTotalCapacity =>
            MaximumRegularCapacity.HasValue
                ? MaximumRegularCapacity.Value +
                  (MaximumAdditionalCapacity ?? 0.0)
                : null;
 
        /// <summary>
        /// Gets the additional capacity required beyond
        /// the global regular capacity.
        /// </summary>
        public double RequiredAdditionalCapacity =>
            MaximumRegularCapacity.HasValue
                ? Math.Max(
                    0.0,
                    TotalRequiredCapacity -
                    MaximumRegularCapacity.Value)
                : 0.0;
 
        /// <summary>
        /// Gets a value indicating whether the aggregated load
        /// fits the regular global capacity.
        /// </summary>
        public bool FitsRegularCapacity =>
            !MaximumRegularCapacity.HasValue ||
            TotalRequiredCapacity <=
                MaximumRegularCapacity.Value;
 
        /// <summary>
        /// Gets a value indicating whether the aggregated load
        /// fits the regular plus additional global capacity.
        /// </summary>
        public bool FitsTotalCapacity =>
            !MaximumTotalCapacity.HasValue ||
            TotalRequiredCapacity <=
                MaximumTotalCapacity.Value;
 
        /// <summary>
        /// Gets the amount exceeding the global maximum capacity.
        /// </summary>
        public double CapacityExcess =>
            MaximumTotalCapacity.HasValue
                ? Math.Max(
                    0.0,
                    TotalRequiredCapacity -
                    MaximumTotalCapacity.Value)
                : 0.0;
 
        /// <summary>
        /// Gets a value indicating whether all item-specific
        /// capacity constraints are respected.
        /// </summary>
        public bool AllItemSpecificCapacitiesSatisfied =>
            _itemLoads.All(
                load => load.FitsTotalCapacity);
 
        /// <summary>
        /// Gets the item loads exceeding an item-specific
        /// capacity limit.
        /// </summary>
        public IReadOnlyList<ItemLoadResult>
            ItemSpecificCapacityViolations =>
                _itemLoads
                    .Where(
                        load =>
                            !load.FitsTotalCapacity)
                    .ToArray();
 
        /// <summary>
        /// Gets a value indicating whether both the global
        /// capacity and all item-specific capacities are respected.
        /// </summary>
        public bool IsFeasible =>
            FitsTotalCapacity &&
            AllItemSpecificCapacitiesSatisfied;
 
        /// <summary>
        /// Returns a textual summary of the resource load,
        /// its available capacity and its feasibility.
        /// </summary>
        /// <returns>
        /// A human-readable description of the resource-load report.
        /// </returns>
        public override string ToString()
        {
            string capacityDescription =
                HasGlobalCapacityConstraint
                    ? $"maximum {MaximumTotalCapacity}"
                    : "no global capacity limit";
 
            return
                $"{ResourceKind} resource {ResourceKey}, " +
                $"period {Period}: required " +
                $"{TotalRequiredCapacity}, " +
                $"{capacityDescription}, " +
                $"feasible {IsFeasible}";
        }
 
        private static double
            CalculateTotalRequiredCapacity(
                IEnumerable<ItemLoadResult> loads)
        {
            double total = 0.0;
 
            foreach (ItemLoadResult load in loads)
            {
                total += load.RequiredCapacity;
 
                if (!double.IsFinite(total))
                {
                    throw new InvalidOperationException(
                        "The aggregated resource load exceeds " +
                        "the supported numerical range.");
                }
            }
 
            return total;
        }
    }
}