Package com.amalgamasimulation.studies.core

Class IncrementalUnitsCapacityStudy

java.lang.Object
com.amalgamasimulation.studies.core.StudyStep
com.amalgamasimulation.studies.core.Study
com.amalgamasimulation.studies.core.IncrementalUnitsCapacityStudy
public abstract class IncrementalUnitsCapacityStudy extends Study
An abstract study that performs iterative capacity expansion on units within a ScenarioStudyStep based on units' utilization and scenario's output improvement criteria.

This study:

  • Identifies the unit with the highest utilization across applicable scenario steps and their descendant steps.
  • Generates a modification to extend the unit’s capacity via unitCapacityExtensionModification(String).
  • Applies this modification to create a new ModifiedScenarioStudyStep.
  • Evaluates whether the change leads to an increase in output compared to the parent or baseline step.
  • Repeats the process up to a configurable number of iterations (maxStepsCount).

The baseline scenario is established from the provided parent step or initialized with an identity modification if no prior results exist. Each incremental step is tracked and available via incrementalSteps().

Subclasses must define the domain-specific logic for output and utilization evaluation and how unit capacity is extended.

See Also:

  • Constructor Details

    • IncrementalUnitsCapacityStudy

      protected IncrementalUnitsCapacityStudy(String name, int maxStepsCount)
      Constructs a new incremental capacity expansion study.
      Parameters:
      maxStepsCount - the maximum number of incremental steps to perform. Each step represents one capacity extension of some unit.

  • Method Details

    • experimentOutput

      public abstract DistributionStatistics experimentOutput(ResultsList results)
      Extracts the primary output metric from a given set of results. This metric is used to assess whether extending unit capacity has led to an improvement.

      This method answers the question "Having a list of simulation results of one or several replications of a single scenario, how do we retrieve its output that represents the system's overall performance?"

      Parameters:
      results - the list of results from a simulation step
      Returns:
      a statistical summary (e.g., total output) representing the experiment's performance
      See Also:

    • unitUtilization

      public abstract DistributionStatistics unitUtilization(String unitId, ResultsList results)
      Computes the utilization statistics for a given unit from a set of results. Utilization is used to determine which units are most heavily loaded and thus are candidates for capacity extension.

      This method answers the question "Having a list of simulation results of a single scenario and the identifier of some unit, how do we retrieve the utilization of this unit observed during the simulation experiment?"

      Parameters:
      unitId - the identifier of the unit
      results - the list of results from a simulation step
      Returns:
      a statistical summary of the unit’s utilization
      See Also:

    • unitsIdList

      public abstract List<String> unitsIdList(org.eclipse.emf.ecore.EObject scenario)
      Retrieves the list of unit identifiers from the given scenario object. These units are evaluated for utilization and considered for capacity extension.

      This method answers the question "Having a scenario data model object, how do we retrieve identifiers of all units considered in the study?"

      Parameters:
      scenario - the scenario data model object from which to extract unit identifiers
      Returns:
      a list of unit identifiers applicable for capacity analysis

    • unitCapacityExtensionModification

      public abstract Modification unitCapacityExtensionModification(String unitId)
      Creates a modification that represents an increase in capacity for the specified unit. This modification will be applied to generate a new simulation scenario.
      Parameters:
      unitId - the identifier of the unit to extend
      Returns:
      a Modification that increases the unit's capacity

    • incrementalSteps

      public List<IncrementalUnitsCapacityStudy.IncrementalStep> incrementalSteps()
      Returns the list of all incremental steps that have been performed in this study.

      Each step contains the input context, unit modified, and output evaluation.

      Returns:
      a list of performed IncrementalUnitsCapacityStudy.IncrementalSteps, in order of execution

    • apply

      public void apply(StudyStep parent)
      Applies the study logic starting from the given parent step.

      If the parent already has results, it is used as the baseline step. Otherwise, an identity-modified step is created and used as the baseline. Then, one incremental capacity extension step is attempted.

      Overrides:
      apply in class Study
      Parameters:
      parent - the study step to apply this study from, expected to be a ScenarioStudyStep

    • initialize

      public void initialize()
      Overrides:
      initialize in class Study

    • isApplicable

      public boolean isApplicable(StudyStep studyStep)
      Determines whether this study can be applied to the given study step.

      This is true if the step is a ScenarioStudyStep and the associated scenario contains at least one unit identifier.

      Overrides:
      isApplicable in class Study
      Parameters:
      studyStep - the study step to check
      Returns:
      true if the study can be applied, false otherwise

    • onStepCompleted

      public void onStepCompleted(ReplicationStudyStep completedReplicationStep)
      Overrides:
      onStepCompleted in class Study

    • maxStepsCount

      public int maxStepsCount()