CadetCareerProblem – Other Adjustments Methods

parameter_sanity_check()

Perform a Full Sanity Check on the Instance Parameters and Value Parameters.

This method serves as a high-level entry point for validating the integrity and feasibility of all input data used in the AFSC cadet-career field assignment model. It ensures that parameters (self.parameters) and value parameters (self.value_parameters) are properly defined, logically consistent, and free of structural or numerical issues prior to model execution.

The method internally delegates the actual check logic to afccp.data.adjustments.parameter_sanity_check(self), which audits everything from AFSC quotas, cadet eligibility, objective constraints, preference matrices, tier distributions, and utility monotonicity.

Parameters:

• self: CadetCareerProblem The instance of the assignment problem containing the full dataset and modeling structure.

Returns:

• None: This method prints a summary of all issues detected but does not return any value. It may raise a ValueError if the value_parameters are missing or invalid.

Examples:

# Run a full input audit before solving
instance.parameter_sanity_check()

Example output (truncated for brevity):

3 ISSUE: AFSC '15A' quota_min (15) > number of eligible cadets (13)
4 ISSUE: Cadet 41 has no preferences and is therefore eligible for nothing.
5 ISSUE: Objective 'Tier 2' has value function with unsorted breakpoints.

See Also:

• parameter_sanity_check: Full implementation of the internal logic performing the data validation. ```

Source code in afccp/main.py

def parameter_sanity_check(self):
    """
    Perform a Full Sanity Check on the Instance Parameters and Value Parameters.

    This method serves as a high-level entry point for validating the integrity and feasibility of all input data
    used in the AFSC cadet-career field assignment model. It ensures that parameters (`self.parameters`) and value
    parameters (`self.value_parameters`) are properly defined, logically consistent, and free of structural or
    numerical issues prior to model execution.

    The method internally delegates the actual check logic to
    `afccp.data.adjustments.parameter_sanity_check(self)`, which audits everything from AFSC quotas, cadet eligibility,
    objective constraints, preference matrices, tier distributions, and utility monotonicity.

    Parameters:
    --------
    - self: `CadetCareerProblem`
        The instance of the assignment problem containing the full dataset and modeling structure.

    Returns:
    --------
    - None: This method prints a summary of all issues detected but does not return any value. It may raise a
      `ValueError` if the `value_parameters` are missing or invalid.

    Examples:
    --------
    ```python
    # Run a full input audit before solving
    instance.parameter_sanity_check()
    ```

    Example output (truncated for brevity):
    ```
    3 ISSUE: AFSC '15A' quota_min (15) > number of eligible cadets (13)
    4 ISSUE: Cadet 41 has no preferences and is therefore eligible for nothing.
    5 ISSUE: Objective 'Tier 2' has value function with unsorted breakpoints.
    ```

    See Also:
    --------
    - [`parameter_sanity_check`](../../../../afccp/reference/data/adjustments/#data.adjustments.parameter_sanity_check):
      Full implementation of the internal logic performing the data validation.
    ```
    """

    # Call the function
    afccp.data.adjustments.parameter_sanity_check(self)

create_final_utility_matrix_from_new_formula(printing=None)

Construct the Final Cadet Utility Matrix Using a New Weighted Formula.

This method builds the cadet_utility matrix by applying a new utility scoring formula that combines:

• Ranked ordinal preferences
• Cadet-specified utility values
• Boolean least desired AFSC logic (e.g., last choice, bottom 2, etc.)

The scoring function is applied to each cadet-AFSC pairing based on a normalized mix of ranking and utility to capture more nuanced decision-making behavior. This method is essential for creating the input data used in optimization.

After computing the new utility values, the method also updates the internal parameter sets to ensure consistency between derived structures (e.g., eligibility dictionaries and matrix representations).

Parameters:

• printing (bool, optional): Whether to print progress messages. If None, defaults to self.printing.

Returns:

• None: This method modifies self.parameters in-place with updated cadet utility values and updated preference-derived sets.

Examples:

# Run the transformation step to produce cadet utilities from ranked inputs
instance.create_final_utility_matrix_from_new_formula(printing=True)

See Also:

• create_final_cadet_utility_matrix_from_new_formula: Core function that applies the new weighted formula to calculate cadet utilities.
• parameter_sets_additions: Ensures derived sets such as I^E and J^E are regenerated after utility/preference updates. ```

Source code in afccp/main.py

def create_final_utility_matrix_from_new_formula(self, printing=None):
    """
    Construct the Final Cadet Utility Matrix Using a New Weighted Formula.

    This method builds the `cadet_utility` matrix by applying a new utility scoring formula that combines:

    - Ranked ordinal preferences
    - Cadet-specified utility values
    - Boolean least desired AFSC logic (e.g., last choice, bottom 2, etc.)

    The scoring function is applied to each cadet-AFSC pairing based on a normalized mix of ranking and utility
    to capture more nuanced decision-making behavior. This method is essential for creating the input data used
    in optimization.

    After computing the new utility values, the method also updates the internal parameter sets to ensure consistency
    between derived structures (e.g., eligibility dictionaries and matrix representations).

    Parameters:
    --------
    - printing (bool, optional): Whether to print progress messages. If None, defaults to `self.printing`.

    Returns:
    --------
    - None: This method modifies `self.parameters` in-place with updated cadet utility values and updated
      preference-derived sets.

    Examples:
    --------
    ```python
    # Run the transformation step to produce cadet utilities from ranked inputs
    instance.create_final_utility_matrix_from_new_formula(printing=True)
    ```

    See Also:
    --------
    - [`create_final_cadet_utility_matrix_from_new_formula`](../../../../afccp/reference/data/preferences/#data.preferences.create_final_cadet_utility_matrix_from_new_formula):
      Core function that applies the new weighted formula to calculate cadet utilities.
    - [`parameter_sets_additions`](../../../../afccp/reference/data/adjustments/#data.adjustments.parameter_sets_additions):
      Ensures derived sets such as `I^E` and `J^E` are regenerated after utility/preference updates.
    ```
    """
    if printing is None:
        printing = self.printing

    if printing:
        print("Creating 'Final' cadet utility matrix from the new formula with different conditions...")

    # Update parameters
    self.parameters = afccp.data.preferences.create_final_cadet_utility_matrix_from_new_formula(self.parameters)
    self.parameters = afccp.data.adjustments.parameter_sets_additions(self.parameters)

set_ots_must_matches(printing=None)

Set OTS Cadet Must-Match Constraints Based on Order of Merit.

This method determines which Officer Training School (OTS) cadets must be assigned an AFSC by evaluating their Order of Merit (OM) scores. It sorts the eligible OTS cadets by merit and selects the top ots_accessions (rounded to 99.5%) to be marked as "must match" within the optimization model.

The method modifies the must_match vector and updates the I^Must_Match set accordingly. These constraints are used to enforce that high-ranking OTS cadets must be matched during the assignment process.

If the instance does not include OTS cadets (i.e., 'ots' not in SOCs), the function exits early without making any changes.

Parameters:

• printing (bool, optional): If True, prints logging information about the matching process. If None (default), uses the instance's self.printing attribute.

Returns:

• None: This method updates the instance's parameters attribute in place.

Examples:

instance.set_ots_must_matches(printing=True)

See Also:

• set_ots_must_matches: Underlying function that applies the must-match logic to the parameter dictionary.

Source code in afccp/main.py

def set_ots_must_matches(self, printing=None):
    """
    Set OTS Cadet Must-Match Constraints Based on Order of Merit.

    This method determines which Officer Training School (OTS) cadets must be assigned an AFSC
    by evaluating their Order of Merit (OM) scores. It sorts the eligible OTS cadets by merit and
    selects the top `ots_accessions` (rounded to 99.5%) to be marked as "must match" within the
    optimization model.

    The method modifies the `must_match` vector and updates the `I^Must_Match` set accordingly.
    These constraints are used to enforce that high-ranking OTS cadets must be matched during the
    assignment process.

    If the instance does not include OTS cadets (i.e., 'ots' not in `SOCs`), the function exits early
    without making any changes.

    Parameters:
    --------
    - printing (bool, optional): If True, prints logging information about the matching process.
      If None (default), uses the instance's `self.printing` attribute.

    Returns:
    --------
    - None: This method updates the instance's `parameters` attribute in place.

    Examples:
    --------
    ```python
    instance.set_ots_must_matches(printing=True)
    ```

    See Also:
    --------
    - [`set_ots_must_matches`](../../../../afccp/reference/data/adjustments/#data.adjustments.set_ots_must_matches):
      Underlying function that applies the must-match logic to the parameter dictionary.
    """

    if printing is None:
        printing = self.printing

    if printing:
        print(f"Setting OTS 'must-matches' by sorting OM and selecting top {self.parameters['ots_accessions']} OTS")

    # Set OTS must matches  (No need to adjust parameter sets- I adjust "I^Must_Match" in this function too
    self.parameters = afccp.data.adjustments.set_ots_must_matches(self.parameters)

calculate_qualification_matrix(printing=None)

Generate or Update the Qualification Matrix Based on CIP Codes.

This method regenerates the degree qualification matrix (qual) using CIP codes (cip1, and optionally cip2) mapped to AFSCs via a tiered system. The qualification matrix determines which cadets are eligible for which AFSCs and tags them accordingly as mandatory, desired, permitted, ineligible, or exceptional. It is useful when switching qualification logic or refreshing the matrix after modifying degree information.

Parameters:

• printing (bool, optional): If True, print progress messages to the console. Defaults to the instance's self.printing attribute.

Returns:

• None: The function updates the self.parameters attribute in-place.

Examples:

instance.calculate_qualification_matrix(printing=True)

See Also:

• cip_to_qual_tiers: Generates the tiered qualification matrix based on CIP-to-AFSC logic.
• parameter_sets_additions: Rebuilds internal indexed parameter sets and flags after matrix updates.

Source code in afccp/main.py

def calculate_qualification_matrix(self, printing=None):
    """
    Generate or Update the Qualification Matrix Based on CIP Codes.

    This method regenerates the degree qualification matrix (`qual`) using CIP codes
    (`cip1`, and optionally `cip2`) mapped to AFSCs via a tiered system. The qualification matrix
    determines which cadets are eligible for which AFSCs and tags them accordingly as mandatory,
    desired, permitted, ineligible, or exceptional. It is useful when switching qualification logic
    or refreshing the matrix after modifying degree information.

    Parameters:
    --------
    - printing (bool, optional): If True, print progress messages to the console.
      Defaults to the instance's `self.printing` attribute.

    Returns:
    --------
    - None: The function updates the `self.parameters` attribute in-place.

    Examples:
    --------
    ```python
    instance.calculate_qualification_matrix(printing=True)
    ```

    See Also:
    --------
    - [`cip_to_qual_tiers`](../../../../afccp/reference/data/support/#data.support.cip_to_qual_tiers):
      Generates the tiered qualification matrix based on CIP-to-AFSC logic.
    - [`parameter_sets_additions`](../../../../afccp/reference/data/adjustments/#data.adjustments.parameter_sets_additions):
      Rebuilds internal indexed parameter sets and flags after matrix updates.
    """
    if printing is None:
        printing = self.printing

    if printing:
        print('Adjusting qualification matrix...')
    parameters = copy.deepcopy(self.parameters)

    # Generate new matrix
    if "cip1" in parameters:
        if "cip2" in parameters:
            qual_matrix = afccp.data.support.cip_to_qual_tiers(
                parameters["afscs"][:parameters["M"]], parameters['cip1'], cip2=parameters['cip2'])
        else:
            qual_matrix = afccp.data.support.cip_to_qual_tiers(
                parameters["afscs"][:parameters["M"]], parameters['cip1'])
    else:
        raise ValueError("Error. Need to update the degree tier qualification matrix to include tiers "
                         "('M1' instead of 'M' for example) but don't have CIP codes. Please incorporate this.")

    # Load data back into parameters
    parameters["qual"] = qual_matrix
    parameters["qual_type"] = "Tiers"
    parameters["ineligible"] = (np.core.defchararray.find(qual_matrix, "I") != -1) * 1
    parameters["eligible"] = (parameters["ineligible"] == 0) * 1
    parameters["exception"] = (np.core.defchararray.find(qual_matrix, "E") != -1) * 1
    for t in [1, 2, 3, 4]:
        parameters["tier " + str(t)] = (np.core.defchararray.find(qual_matrix, str(t)) != -1) * 1
    parameters = afccp.data.adjustments.parameter_sets_additions(parameters)
    self.parameters = copy.deepcopy(parameters)