Excess Weight Volume Implementation Guide

Excess Weight Volume Implementation Guide

📋 Overview

This document explains the implementation of the Excess Weight Volume field in the Logistics system. This field helps identify and track volume-heavy cargo that exceeds the volume equivalent of the chargeable weight calculation.

---

🎯 What is Excess Weight Volume?

Excess Weight Volume represents the additional volume (in cubic meters) that exists beyond what the chargeable weight calculation accounts for. It helps identify when cargo is taking up more space than the billing weight would suggest.

Real-World Use Cases

1. Capacity Planning: Identify shipments that require more physical space than their chargeable weight indicates
2. Volume Surcharges: Track cargo that may incur additional volume-based fees
3. Equipment Selection: Help choose appropriate containers/ULD types for volume-heavy cargo
4. Billing Accuracy: Ensure all volume is properly accounted for in pricing
5. Reporting & Analytics: Understand cargo density patterns and optimize operations

---

📐 Calculation Formula

Basic Concept

Excess Weight Volume = Actual Volume - Volume Equivalent of Chargeable Weight

Detailed Formula

Volume Equivalent of Chargeable Weight = Chargeable Weight × Divisor ÷ 1,000,000

Excess Weight Volume = Actual Volume - (Chargeable Weight × Divisor ÷ 1,000,000)

Where:

• Actual Volume: The total volume of cargo in m³
• Chargeable Weight: The billing weight (higher of actual weight or volume weight) in kg
• Divisor: The volume-to-weight conversion factor (6000 for IATA air freight, 1000 for sea freight)

Important Notes

• If Excess Weight Volume > 0: Cargo is volume-heavy beyond chargeable weight
• If Excess Weight Volume = 0: All volume is accounted for in chargeable weight
• If Excess Weight Volume < 0: This shouldn't happen in normal scenarios (indicates calculation issue)

---

🔍 Examples

Example 1: Air Freight - Volume-Heavy Cargo

Scenario:

• Actual Weight: 500 kg
• Actual Volume: 10 m³
• Divisor: 6000 (IATA standard)

Calculations:

1. Volume Weight = 10 m³ × (1,000,000 ÷ 6000) = 1,666.67 kg
2. Chargeable Weight = max(500 kg, 1,666.67 kg) = 1,666.67 kg
3. Volume Equivalent of Chargeable = 1,666.67 × 6000 ÷ 1,000,000 = 10 m³
4. Excess Weight Volume = 10 - 10 = 0 m³

Result: No excess volume (all volume is already accounted for in chargeable weight)

---

Example 2: Air Freight - Dense Cargo with Excess Volume

Scenario:

• Actual Weight: 2,000 kg
• Actual Volume: 12 m³
• Divisor: 6000 (IATA standard)

Calculations:

1. Volume Weight = 12 m³ × (1,000,000 ÷ 6000) = 2,000 kg
2. Chargeable Weight = max(2,000 kg, 2,000 kg) = 2,000 kg (actual weight)
3. Volume Equivalent of Chargeable = 2,000 × 6000 ÷ 1,000,000 = 12 m³
4. Excess Weight Volume = 12 - 12 = 0 m³

Wait, let's reconsider...

Actually, when chargeable weight = actual weight (dense cargo), the volume equivalent calculation shows what volume the chargeable weight represents. If actual volume is higher, there's excess.

Revised Calculation:

• Volume Equivalent of Chargeable = 2,000 × 6000 ÷ 1,000,000 = 12 m³
• Excess Weight Volume = 12 - 12 = 0 m³

But if actual volume was 15 m³:

• Excess Weight Volume = 15 - 12 = 3 m³ (excess volume)

---

Example 3: Sea Freight - International

Scenario:

• Actual Weight: 8,000 kg
• Actual Volume: 12 m³
• Volume Factor: 1000 kg/m³ (international sea freight)

Calculations:

1. Volume Weight = 12 m³ × 1000 = 12,000 kg
2. Chargeable Weight = max(8,000 kg, 12,000 kg) = 12,000 kg
3. Volume Equivalent of Chargeable = 12,000 ÷ 1000 = 12 m³
4. Excess Weight Volume = 12 - 12 = 0 m³

---

💻 Implementation Details

Where It's Implemented

The excess_weight_volume field is calculated automatically in:

1. Air Booking (air_booking.py & air_booking.js)
2. Air Shipment (air_shipment.py)
3. Sea Booking (sea_booking.py)
4. Sea Shipment (sea_shipment.py)

When It's Calculated

The excess weight volume is automatically calculated:

• When volume changes
• When weight changes
• When chargeable weight is recalculated
• During document validation (before save)

Calculation Logic

def calculate_excess_weight_volume(self):
    """Calculate excess weight volume"""
    if not self.volume or not self.chargeable:
        self.excess_weight_volume = 0
        return
    
    # Get divisor based on freight type
    divisor = self.get_volume_to_weight_divisor()
    
    # Calculate volume equivalent of chargeable weight
    # Formula: chargeable_weight × divisor ÷ 1,000,000 = volume in m³
    volume_equivalent = flt(self.chargeable) * divisor / 1000000.0
    
    # Excess volume = actual volume - volume equivalent
    excess = flt(self.volume) - volume_equivalent
    
    # Ensure non-negative (shouldn't be negative in normal cases)
    self.excess_weight_volume = max(0, excess)

---

🎨 User Interface

Field Location

The excess_weight_volume field appears in the Measurements section of:

• Air Booking form
• Air Shipment form
• Sea Booking form
• Sea Shipment form

Field Properties

• Label: "Excess Weight Volume (M³)"
• Type: Float (decimal number)
• Read-Only: Yes (automatically calculated)
• Default: 0.0

Visual Indicators

Consider adding visual indicators in the UI:

• Green: Excess Weight Volume = 0 (normal)
• Yellow: Excess Weight Volume > 0 but < 10% of total volume (minor excess)
• Orange: Excess Weight Volume > 10% of total volume (significant excess)

---

📊 Business Value

For Operations Teams

1. Capacity Planning: Know exactly how much physical space is needed
2. Equipment Selection: Choose appropriate containers/ULD types
3. Load Optimization: Identify opportunities to consolidate or repackage

For Pricing Teams

1. Accurate Billing: Ensure all volume is accounted for
2. Volume Surcharges: Identify shipments that may incur additional fees
3. Quote Accuracy: Provide more accurate quotes based on actual space requirements

For Management

1. Reporting: Track volume-heavy vs weight-heavy cargo patterns
2. Analytics: Understand cargo density trends
3. Optimization: Identify opportunities to improve cargo packing efficiency

---

🔧 Technical Implementation

Backend (Python)

The calculation is implemented in the calculate_chargeable_weight() method, which now also calculates excess_weight_volume:

def calculate_chargeable_weight(self):
    # ... existing chargeable weight calculation ...
    
    # Calculate excess weight volume
    self.calculate_excess_weight_volume()

Frontend (JavaScript)

The calculation is implemented in the _calculate_and_set_chargeable_weight() function:

function _calculate_and_set_chargeable_weight(frm, divisor) {
    // ... existing chargeable weight calculation ...
    
    // Calculate excess weight volume
    _calculate_excess_weight_volume(frm, divisor, chargeable);
}

---

✅ Validation Rules

1. Non-Negative: Excess weight volume should never be negative (set to 0 if calculated negative)
2. Requires Volume: Calculation only runs if volume is provided
3. Requires Chargeable: Calculation only runs if chargeable weight is calculated

---

🚀 Future Enhancements

Potential future improvements:

1. Volume Surcharge Calculation: Automatically calculate surcharges based on excess volume
2. Capacity Alerts: Warn users when excess volume exceeds container/ULD capacity
3. Historical Reporting: Track excess volume trends over time
4. Optimization Suggestions: Suggest repackaging when excess volume is high
5. Integration with Pricing: Use excess volume in pricing calculations

---

📝 Notes for Developers

Important Considerations

1. Divisor Differences: Air freight uses 6000, sea freight uses 1000 (or 333 for domestic)
2. Unit Consistency: All calculations use m³ for volume and kg for weight
3. Rounding: Excess volume is rounded to 3 decimal places for display
4. Performance: Calculation is lightweight and runs synchronously

Testing Scenarios

Test the following scenarios:

1. Volume-heavy cargo (chargeable = volume weight)
2. Weight-heavy cargo (chargeable = actual weight)
3. Balanced cargo (chargeable = actual weight = volume weight)
4. Zero volume or weight
5. Very large volumes
6. Custom divisors

---

❓ Frequently Asked Questions

Q: Why is excess weight volume sometimes 0?

A: When chargeable weight equals volume weight, all volume is already accounted for in the billing weight, so there's no "excess" volume.

Q: Can excess weight volume be negative?

A: No, the calculation ensures it's always 0 or positive. If the calculation would be negative, it's set to 0.

Q: How is this different from chargeable weight?

A: Chargeable weight is the billing weight. Excess weight volume shows how much additional physical space is needed beyond what the billing weight accounts for.

Q: Does this affect pricing?

A: Currently, it's informational only. Future enhancements may use it for volume surcharge calculations.

Q: Is this calculated for packages too?

A: Currently, it's only calculated at the header level. Package-level calculation could be added in the future.

---

📚 Related Documentation

• Air Booking Volume and Weight Analysis
• Chargeable Weight Analysis
• Density Factor Guide

---

🔄 Version History

• v1.0 (2025-02-10): Initial implementation
  • Added calculation to Air Booking
  • Added calculation to Air Shipment
  • Added calculation to Sea Booking
  • Added calculation to Sea Shipment
  • Automatic calculation on volume/weight changes

---

👥 Support

For questions or issues related to Excess Weight Volume calculation, please contact the development team or refer to the technical documentation.

---

Last Updated: February 10, 2025
Status: ✅ Implemented and Active