feat: add SHAFT model with MECHANICAL_EFFICIENCY for compressor trains

- Add SHAFT model type with MECHANICAL_EFFICIENCY field
- Add MECHANICAL_EFFICIENCY directly to simplified trains
- Add deprecation warnings for POWER_ADJUSTMENT_CONSTANT/FACTOR
- Add validation for mutual exclusivity
- Update documentation with migration guide

Author: kjbrak

docs/docs/about/migration_guides/mechanical_efficiency.md

@@ -0,0 +1,90 @@
+---
+title: Mechanical Efficiency Migration
+description: Migrating from POWER_ADJUSTMENT_FACTOR to SHAFT with MECHANICAL_EFFICIENCY
+sidebar_position: -16
+---
+
+# Migrating to SHAFT with MECHANICAL_EFFICIENCY
+
+This guide explains how to migrate from the deprecated `POWER_ADJUSTMENT_FACTOR` and `POWER_ADJUSTMENT_CONSTANT` parameters to the new `SHAFT` model with `MECHANICAL_EFFICIENCY`.
+
+## Why Migrate?
+
+The legacy power adjustment parameters were empirical corrections without clear physical meaning. The new approach provides:
+
+- **Physical clarity**: Mechanical efficiency represents real-world losses in bearings, gearboxes, and seals
+- **Better documentation**: Efficiency values can be traced to equipment specifications
+- **Future compatibility**: Legacy parameters will be removed in a future version
+
+## Conversion Formula
+
+$$
+\eta_{mechanical} = \frac{1}{\text{POWER\_ADJUSTMENT\_FACTOR}}
+$$
+
+For example: `POWER_ADJUSTMENT_FACTOR: 1.05` → `MECHANICAL_EFFICIENCY: 0.952`
+
+:::note
+`POWER_ADJUSTMENT_CONSTANT` has no direct equivalent. If you used a constant offset, consult the eCalc team.
+:::
+
+## Migration Examples
+
+### Common-Shaft Trains
+
+For `VARIABLE_SPEED_COMPRESSOR_TRAIN`, `SINGLE_SPEED_COMPRESSOR_TRAIN`, and `VARIABLE_SPEED_COMPRESSOR_TRAIN_MULTIPLE_STREAMS_AND_PRESSURES`:
+
+**Before:**
+```yaml
+- NAME: export_compressor
+  TYPE: VARIABLE_SPEED_COMPRESSOR_TRAIN
+  POWER_ADJUSTMENT_FACTOR: 1.05
+  ...
+```
+
+**After:**
+```yaml
+- NAME: export_shaft
+  TYPE: SHAFT
+  MECHANICAL_EFFICIENCY: 0.952
+
+- NAME: export_compressor
+  TYPE: VARIABLE_SPEED_COMPRESSOR_TRAIN
+  SHAFT: export_shaft
+  ...
+```
+
+:::note
+Each `SHAFT` can only be used by one compressor train. Create separate shaft models if you have multiple trains.
+:::
+
+### Simplified Trains
+
+For `SIMPLIFIED_VARIABLE_SPEED_COMPRESSOR_TRAIN`, set `MECHANICAL_EFFICIENCY` directly on the train:
+
+**Before:**
+```yaml
+- NAME: simple_train
+  TYPE: SIMPLIFIED_VARIABLE_SPEED_COMPRESSOR_TRAIN
+  POWER_ADJUSTMENT_FACTOR: 1.08
+  ...
+```
+
+**After:**
+```yaml
+- NAME: simple_train
+  TYPE: SIMPLIFIED_VARIABLE_SPEED_COMPRESSOR_TRAIN
+  MECHANICAL_EFFICIENCY: 0.926
+  ...
+```
+
+## Troubleshooting
+
+**Cannot specify both SHAFT and POWER_ADJUSTMENT_FACTOR**: Remove the legacy parameter when using `SHAFT` or `MECHANICAL_EFFICIENCY`.
+
+**SHAFT is referenced by multiple trains**: Each shaft can only be used by one train. Create separate shaft models.
+
+## Further Reading
+
+- [SHAFT Reference](/about/references/SHAFT.md)
+- [MECHANICAL_EFFICIENCY Reference](/about/references/MECHANICAL_EFFICIENCY.md)

docs/docs/about/modelling/setup/installations/compressor_models_in_calculations/variable_speed_compressor_train_model_with_multiple_streams_and_pressures.md

@@ -26,7 +26,8 @@ ENERGY_USAGE_MODEL:
   SUCTION_PRESSURE: <suction pressure expression>
   DISCHARGE_PRESSURE: <discharge pressure expression>
   INTERSTAGE_CONTROL_PRESSURE: <interstage control pressure expression>
-  POWER_ADJUSTMENT_CONSTANT: <Optional constant MW adjustment added to the model>
+  SHAFT: <Optional reference to a SHAFT model for mechanical efficiency>
+  POWER_ADJUSTMENT_CONSTANT: <Deprecated. Use SHAFT with MECHANICAL_EFFICIENCY instead.>
 ~~~~~~~~
 
 The number of elements in [RATE_PER_STREAM](/about/references/RATE_PER_STREAM.md) must correspond to the number of streams defined for the model referenced in

docs/docs/about/modelling/setup/models/compressor_modelling/compressor_models_types/simplified_variable_speed_compressor_train_model.md

@@ -27,11 +27,12 @@ stages are calculated at run-time based on input data.
 MODELS:
   - NAME: <model name>
     TYPE: SIMPLIFIED_VARIABLE_SPEED_COMPRESSOR_TRAIN
-    FLUID_MODEL: <reference to fluid model, must be defined in MODELS
+    FLUID_MODEL: <reference to fluid model, must be defined in MODELS>
     COMPRESSOR_TRAIN: <compressor train specification>
-    POWER_ADJUSTMENT_CONSTANT: <Optional constant MW adjustment added to the model>
+    MECHANICAL_EFFICIENCY: <Optional. Mechanical efficiency applied to all stages. Default 1.0 (no losses). Value must be > 0 and ≤ 1.>
+    POWER_ADJUSTMENT_CONSTANT: <Deprecated. Use MECHANICAL_EFFICIENCY instead.>
     MAXIMUM_POWER: <Optional constant MW maximum power the compressor train can require>
-    CALCULATE_MAX_RATE: <Optional. compressor train max standard rate [Sm3/day] in result if set to true. Default false. Use with caution. This will increase runtime significantly. >
+    CALCULATE_MAX_RATE: <Optional. compressor train max standard rate [Sm3/day] in result if set to true. Default false. Use with caution. This will increase runtime significantly.>
 ~~~~~~~~
 
 ### Simplified compressor train model with known compressor stages
@@ -42,14 +43,14 @@ MODELS:
   - NAME: <model name>
     TYPE: SIMPLIFIED_VARIABLE_SPEED_COMPRESSOR_TRAIN
     FLUID_MODEL: <reference to fluid model>
+    MECHANICAL_EFFICIENCY: <Optional. Default 1.0>
     COMPRESSOR_TRAIN:
       STAGES:
         - INLET_TEMPERATURE: <inlet temperature in Celsius for stage>
           COMPRESSOR_CHART: <reference to compressor chart model for first stage, must be defined in MODELS or FACILITY_INPUTS>
         - INLET_TEMPERATURE: <inlet temperature in Celsius for stage>
           COMPRESSOR_CHART: <reference to compressor chart model for second stage, must be defined in MODELS or FACILITY_INPUTS>
         - ... and so forth for each stage in the train
-    POWER_ADJUSTMENT_CONSTANT: <Optional constant MW adjustment added to the model>
     MAXIMUM_POWER: <Optional constant MW maximum power the compressor train can require>
 ~~~~~~~~
 
@@ -68,11 +69,11 @@ MODELS:
   - NAME: <model name>
     TYPE: SIMPLIFIED_VARIABLE_SPEED_COMPRESSOR_TRAIN
     FLUID_MODEL: <reference to fluid model>
+    MECHANICAL_EFFICIENCY: <Optional. Default 1.0>
     COMPRESSOR_TRAIN:
       MAXIMUM_PRESSURE_RATIO_PER_STAGE: <maximum pressure ratio per stage>
       COMPRESSOR_CHART: <reference to compressor chart model used for all stages, must be defined in [MODELS] or [FACILITY_INPUTS]>
       INLET_TEMPERATURE: <inlet temperature for all stages>
-    POWER_ADJUSTMENT_CONSTANT: <Optional constant MW adjustment added to the model>
 ~~~~~~~~
 
 ## Examples

docs/docs/about/modelling/setup/models/compressor_modelling/compressor_models_types/single_speed_compressor_train_model.md

@@ -24,10 +24,11 @@ This means that a single speed compressor model needs the following to be define
 
 The following keywords are optional for a single speed compressor model:
 
+- [SHAFT](/about/references/SHAFT.md) - Reference to a shaft model with mechanical efficiency
 - [MAXIMUM_DISCHARGE_PRESSURE](/about/references/MAXIMUM_DISCHARGE_PRESSURE.md)
-- [POWER_ADJUSTMENT_CONSTANT](/about/references/POWER_ADJUSTMENT_CONSTANT.md)
 - [MAXIMUM_POWER](/about/references/MAXIMUM_POWER.md)
 - [CALCULATE_MAX_RATE](/about/references/CALCULATE_MAX_RATE.md)
+- [POWER_ADJUSTMENT_CONSTANT](/about/references/POWER_ADJUSTMENT_CONSTANT.md) *(Deprecated - use SHAFT instead)*
 
 The model is defined under the main keyword [MODELS](/about/references/MODELS.md) in the format
 
@@ -53,7 +54,8 @@ MODELS:
           CONTROL_MARGIN_UNIT: <FRACTION or PERCENTAGE, default is PERCENTAGE>
           PRESSURE_DROP_AHEAD_OF_STAGE: <Pressure drop before compression stage [in bar]>
         - ... and so forth for each stage in the train
-    POWER_ADJUSTMENT_CONSTANT: <Optional constant MW adjustment added to the model>
+    SHAFT: <Optional reference to a SHAFT model for mechanical efficiency>
     MAXIMUM_POWER: <Optional constant MW maximum power the compressor train can require>
+    POWER_ADJUSTMENT_CONSTANT: <Deprecated. Use SHAFT with MECHANICAL_EFFICIENCY instead.>
     CALCULATE_MAX_RATE: <Optional compressor train max standard rate [Sm3/day] in result if set to true. Default false. Use with caution. This will increase runtime significantly. >
 ~~~~~~~~

docs/docs/about/modelling/setup/models/compressor_modelling/compressor_models_types/variable_speed_compressor_train_model.md

@@ -58,8 +58,9 @@ MODELS:
           PRESSURE_DROP_AHEAD_OF_STAGE: <Pressure drop before compression stage [in bar]>
           CONTROL_MARGIN_UNIT: <FRACTION or PERCENTAGE, default is PERCENTAGE>
         - ... and so forth for each stage in the train
-    POWER_ADJUSTMENT_CONSTANT: <Optional constant MW adjustment added to the model>
+    SHAFT: <Optional reference to a SHAFT model for mechanical efficiency>
     MAXIMUM_POWER: <Optional constant MW maximum power the compressor train can require>
+    POWER_ADJUSTMENT_CONSTANT: <Deprecated. Use SHAFT with MECHANICAL_EFFICIENCY instead.>
     CALCULATE_MAX_RATE: <Optional compressor train max standard rate [Sm3/day] in result if set to true. Default false. Use with caution. This will increase runtime significantly. >
     PRESSURE_CONTROL: <method for pressure control, DOWNSTREAM_CHOKE (default), UPSTREAM_CHOKE, , INDIVIDUAL_ASV_PRESSURE, INDIVIDUAL_ASV_RATE or COMMON_ASV>
 ~~~~~~~~

docs/docs/about/modelling/setup/models/compressor_modelling/compressor_models_types/variable_speed_compressor_train_model_with_multiple_streams_and_pressures.md

@@ -53,6 +53,7 @@ MODELS:
         CONTROL_MARGIN_UNIT: <FRACTION or PERCENTAGE, default is PERCENTAGE>
         PRESSURE_DROP_AHEAD_OF_STAGE: <Pressure drop before compression stage [in bar]>
       - ...
+    SHAFT: <Optional reference to a SHAFT model for mechanical efficiency>
     MAXIMUM_POWER: <Optional constant MW maximum power the compressor train can require>
 ~~~~~~~~
 

docs/docs/about/references/MECHANICAL_EFFICIENCY.md

@@ -0,0 +1,77 @@
+# MECHANICAL_EFFICIENCY
+
+[MODELS](/about/references/MODELS.md) / 
+[SHAFT](/about/references/SHAFT.md) /
+[MECHANICAL_EFFICIENCY](/about/references/MECHANICAL_EFFICIENCY.md)
+
+## Description
+
+`MECHANICAL_EFFICIENCY` defines the ratio of useful mechanical work output to the total mechanical work input for a shaft system. It accounts for power losses in bearings, gearboxes, seals, and couplings.
+
+The mechanical efficiency is used in a [SHAFT](/about/references/SHAFT.md) model to calculate the shaft power required from the driver:
+
+$$
+P_{shaft} = \frac{P_{gas}}{\eta_{mechanical}}
+$$
+
+## Format
+
+~~~~yaml
+MODELS:
+  - NAME: <shaft name>
+    TYPE: SHAFT
+    MECHANICAL_EFFICIENCY: <value>
+~~~~
+
+:::note Simplified trains
+For `SIMPLIFIED_VARIABLE_SPEED_COMPRESSOR_TRAIN`, `MECHANICAL_EFFICIENCY` is set directly on the train model (not via a separate SHAFT). It applies uniformly to all stages and defaults to 1.0 if not specified.
+:::
+
+## Example
+
+~~~~yaml
+MODELS:
+  - NAME: compressor_shaft
+    TYPE: SHAFT
+    MECHANICAL_EFFICIENCY: 0.95  # 95% efficiency, 5% losses
+~~~~
+
+## Value Range
+
+| Constraint | Value | Description |
+|------------|-------|-------------|
+| Minimum | > 0 | Must be positive (exclusive) |
+| Maximum | ≤ 1.0 | Cannot exceed 100% efficiency |
+
+### Typical Values
+
+| Drive Configuration | Typical Range | Typical Losses | Notes |
+|---------------------|---------------|----------------|-------|
+| Direct drive | 0.96 - 0.98 | 2-4% | Bearings (1-2%) + seals/couplings (1-2%) |
+| With gearbox | 0.93 - 0.96 | 4-7% | Adds gearbox losses (2-3%) |
+
+:::note
+These are approximate ranges for the **total** mechanical efficiency of the drive train. The actual value depends on equipment design, operating conditions, and manufacturer data. A typical default of ~0.95 (5% losses) covers a common configuration with gearbox.
+:::
+
+## Physical Interpretation
+
+The mechanical efficiency accounts for power losses in the drivetrain between 
+the driver (motor/turbine) and the compressor, including:
+
+- **Bearing losses**: Friction in shaft support bearings  
+- **Gearbox losses**: Friction and churning in gear systems (if present)
+- **Seal and coupling losses**: Minor friction in auxiliary components
+
+:::note Constant efficiency assumption
+In reality, frictional losses scale approximately with the square of rotational speed. 
+However, eCalc assumes a **constant** mechanical efficiency across all operating points. 
+Choose a representative value for typical operating conditions, or consult vendor data 
+for the expected speed range.
+:::
+
+## See Also
+
+- [SHAFT](/about/references/SHAFT.md)
+- [EFFICIENCY](/about/references/EFFICIENCY.md)
+- [POLYTROPIC_EFFICIENCY](/about/references/POLYTROPIC_EFFICIENCY.md)

docs/docs/about/references/POWER_ADJUSTMENT_CONSTANT.md

@@ -3,6 +3,10 @@
 [MODELS](/about/references/MODELS.md) / 
 [POWER_ADJUSTMENT_CONSTANT](/about/references/POWER_ADJUSTMENT_CONSTANT.md)
 
+:::warning Deprecated
+This parameter is deprecated and will be removed in a future version. Use [SHAFT](/about/references/SHAFT.md) with [MECHANICAL_EFFICIENCY](/about/references/MECHANICAL_EFFICIENCY.md) instead for a physically meaningful way to model mechanical losses.
+:::
+
 ## Description
 Optional constant MW adjustment added to the model. Only added if (electrical) POWER > 0. Can be used in combination with [POWER_ADJUSTMENT_FACTOR](/about/references/POWER_ADJUSTMENT_FACTOR.md).
 
@@ -18,6 +22,7 @@ MODELS:
 
 ## Example
 
+**Deprecated usage:**
 ~~~~~yaml
 MODELS:
   - NAME: simple_compressor
@@ -26,11 +31,4 @@ MODELS:
     POWER_ADJUSTMENT_CONSTANT: 10 #MW
 ~~~~~
 
-~~~~~yaml
-MODELS:
-  - NAME: simple_compressor
-    TYPE: SIMPLIFIED_VARIABLE_SPEED_COMPRESSOR_TRAIN
-    ...
-    POWER_ADJUSTMENT_CONSTANT: 10 #MW
-    POWER_ADJUSTMENT_FACTOR: 1.2 
-~~~~~
+**Recommended migration:** See the [Mechanical Efficiency Migration Guide](/about/migration_guides/mechanical_efficiency.md).

docs/docs/about/references/POWER_ADJUSTMENT_FACTOR.md

@@ -3,6 +3,10 @@
 [MODELS](/about/references/MODELS.md) / 
 [POWER_ADJUSTMENT_FACTOR](/about/references/POWER_ADJUSTMENT_FACTOR.md)
 
+:::warning Deprecated
+This parameter is deprecated and will be removed in a future version. Use [SHAFT](/about/references/SHAFT.md) with [MECHANICAL_EFFICIENCY](/about/references/MECHANICAL_EFFICIENCY.md) instead for a physically meaningful way to model mechanical losses.
+:::
+
 ## Description
 Optional factor adjusting the power in the model. The power is multiplied by this factor. Can be used in combination with [POWER_ADJUSTMENT_CONSTANT](/about/references/POWER_ADJUSTMENT_CONSTANT.md).
 
@@ -18,6 +22,7 @@ MODELS:
 
 ## Example
 
+**Deprecated usage:**
 ~~~~~yaml
 MODELS:
   - NAME: simple_compressor
@@ -26,11 +31,4 @@ MODELS:
     POWER_ADJUSTMENT_FACTOR: 1.2 
 ~~~~~
 
-~~~~~yaml
-MODELS:
-  - NAME: simple_compressor
-    TYPE: SIMPLIFIED_VARIABLE_SPEED_COMPRESSOR_TRAIN
-    ...
-    POWER_ADJUSTMENT_CONSTANT: 10 #MW
-    POWER_ADJUSTMENT_FACTOR: 1.2 
-~~~~~
+**Recommended migration:** See the [Mechanical Efficiency Migration Guide](/about/migration_guides/mechanical_efficiency.md).