Skip to content

Commit 5b3dce0

Browse files
kjbrakkjbrak
committed
feat: add MECHANICAL_EFFICIENCY to compressor train types
- Add mechanical_efficiency field (0 < η ≤ 1, default 1.0) to all train types - Shaft domain class owns efficiency, calculates shaft_power = gas_power / η - Mutual exclusivity with deprecated POWER_ADJUSTMENT_* params - Add docs, migration guide, and parametrized tests
1 parent a7aeabd commit 5b3dce0

18 files changed

Lines changed: 734 additions & 130 deletions

File tree

‎docs/docs/about/migration_guides/mechanical_efficiency.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
---
2+
title: Mechanical Efficiency Migration
3+
description: Migrating from POWER_ADJUSTMENT_FACTOR to MECHANICAL_EFFICIENCY
4+
sidebar_position: -16
5+
---
6+
7+
# Migrating to MECHANICAL_EFFICIENCY
8+
9+
This guide explains how to migrate from the deprecated `POWER_ADJUSTMENT_FACTOR` and `POWER_ADJUSTMENT_CONSTANT` parameters to the new `MECHANICAL_EFFICIENCY` parameter.
10+
11+
## Why Migrate?
12+
13+
The legacy power adjustment parameters were empirical corrections without clear physical meaning. The new approach provides:
14+
15+
- **Physical clarity**: Mechanical efficiency represents real-world losses in bearings, gearboxes, and seals
16+
- **Better documentation**: Efficiency values can be traced to equipment specifications
17+
- **Future compatibility**: Legacy parameters will be removed in a future version
18+
19+
## Conversion Formula
20+
21+
$$
22+
\eta_{mechanical} = \frac{1}{\text{POWER\_ADJUSTMENT\_FACTOR}}
23+
$$
24+
25+
For example: `POWER_ADJUSTMENT_FACTOR: 1.05` → `MECHANICAL_EFFICIENCY: 0.952`
26+
27+
:::note
28+
`POWER_ADJUSTMENT_CONSTANT` has no direct equivalent. If you used a constant offset, consult the eCalc team.
29+
:::
30+
31+
## Migration Examples
32+
33+
### All Compressor Train Types
34+
35+
For all compressor train types (`VARIABLE_SPEED_COMPRESSOR_TRAIN`, `SINGLE_SPEED_COMPRESSOR_TRAIN`, `VARIABLE_SPEED_COMPRESSOR_TRAIN_MULTIPLE_STREAMS_AND_PRESSURES`, and `SIMPLIFIED_VARIABLE_SPEED_COMPRESSOR_TRAIN`), set `MECHANICAL_EFFICIENCY` directly on the train model:
36+
37+
**Before:**
38+
```yaml
39+
MODELS:
40+
- NAME: export_compressor
41+
TYPE: VARIABLE_SPEED_COMPRESSOR_TRAIN
42+
POWER_ADJUSTMENT_FACTOR: 1.05
43+
FLUID_MODEL: medium_gas
44+
COMPRESSOR_TRAIN:
45+
STAGES:
46+
- INLET_TEMPERATURE: 30
47+
COMPRESSOR_CHART: compressor_chart_ref
48+
```
49+
50+
**After:**
51+
```yaml
52+
MODELS:
53+
- NAME: export_compressor
54+
TYPE: VARIABLE_SPEED_COMPRESSOR_TRAIN
55+
MECHANICAL_EFFICIENCY: 0.952 # = 1/1.05, accounts for 5% mechanical losses
56+
FLUID_MODEL: medium_gas
57+
COMPRESSOR_TRAIN:
58+
STAGES:
59+
- INLET_TEMPERATURE: 30
60+
COMPRESSOR_CHART: compressor_chart_ref
61+
```
62+
63+
### Simplified Trains
64+
65+
The same pattern applies to `SIMPLIFIED_VARIABLE_SPEED_COMPRESSOR_TRAIN`:
66+
67+
**Before:**
68+
```yaml
69+
MODELS:
70+
- NAME: simple_train
71+
TYPE: SIMPLIFIED_VARIABLE_SPEED_COMPRESSOR_TRAIN
72+
POWER_ADJUSTMENT_FACTOR: 1.08
73+
FLUID_MODEL: medium_gas
74+
COMPRESSOR_TRAIN:
75+
STAGES:
76+
- INLET_TEMPERATURE: 30
77+
COMPRESSOR_CHART: generic_chart
78+
```
79+
80+
**After:**
81+
```yaml
82+
MODELS:
83+
- NAME: simple_train
84+
TYPE: SIMPLIFIED_VARIABLE_SPEED_COMPRESSOR_TRAIN
85+
MECHANICAL_EFFICIENCY: 0.926 # = 1/1.08
86+
FLUID_MODEL: medium_gas
87+
COMPRESSOR_TRAIN:
88+
STAGES:
89+
- INLET_TEMPERATURE: 30
90+
COMPRESSOR_CHART: generic_chart
91+
```
92+
93+
## Troubleshooting
94+
95+
**Cannot specify both MECHANICAL_EFFICIENCY and POWER_ADJUSTMENT_FACTOR**: Remove the legacy parameter when using `MECHANICAL_EFFICIENCY`. The two approaches are mutually exclusive.
96+
97+
**MECHANICAL_EFFICIENCY must be in range (0, 1]**: Ensure your value is greater than 0 and at most 1.0. Use the conversion formula above if migrating from `POWER_ADJUSTMENT_FACTOR`.
98+
99+
## Further Reading
100+
101+
- [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‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,9 +26,12 @@ ENERGY_USAGE_MODEL:
2626
SUCTION_PRESSURE: <suction pressure expression>
2727
DISCHARGE_PRESSURE: <discharge pressure expression>
2828
INTERSTAGE_CONTROL_PRESSURE: <interstage control pressure expression>
29-
POWER_ADJUSTMENT_CONSTANT: <Optional constant MW adjustment added to the model>
3029
~~~~~~~~
3130

31+
:::warning Deprecated Parameters
32+
The `POWER_ADJUSTMENT_CONSTANT` parameter is deprecated. Use `MECHANICAL_EFFICIENCY` on the train model definition instead.
33+
:::
34+
3235
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
3336
[COMPRESSOR_TRAIN_MODEL](/about/references/COMPRESSOR_TRAIN_MODEL.md).
3437

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

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -27,13 +27,17 @@ stages are calculated at run-time based on input data.
2727
MODELS:
2828
- NAME: <model name>
2929
TYPE: SIMPLIFIED_VARIABLE_SPEED_COMPRESSOR_TRAIN
30-
FLUID_MODEL: <reference to fluid model, must be defined in MODELS
30+
FLUID_MODEL: <reference to fluid model, must be defined in MODELS>
3131
COMPRESSOR_TRAIN: <compressor train specification>
32-
POWER_ADJUSTMENT_CONSTANT: <Optional constant MW adjustment added to the model>
32+
MECHANICAL_EFFICIENCY: <Optional. Mechanical efficiency applied to all stages. Default 1.0 (no losses). Value must be > 0 and ≤ 1.>
3333
MAXIMUM_POWER: <Optional constant MW maximum power the compressor train can require>
34-
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. >
34+
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.>
3535
~~~~~~~~
3636

37+
:::warning Deprecated Parameters
38+
The `POWER_ADJUSTMENT_CONSTANT` and `POWER_ADJUSTMENT_FACTOR` parameters are deprecated. Use `MECHANICAL_EFFICIENCY` instead.
39+
:::
40+
3741
### Simplified compressor train model with known compressor stages
3842
When the compressor stages are known, each stage is defined with a compressor chart and an inlet temperature:
3943

@@ -42,14 +46,14 @@ MODELS:
4246
- NAME: <model name>
4347
TYPE: SIMPLIFIED_VARIABLE_SPEED_COMPRESSOR_TRAIN
4448
FLUID_MODEL: <reference to fluid model>
49+
MECHANICAL_EFFICIENCY: <Optional. Default 1.0>
4550
COMPRESSOR_TRAIN:
4651
STAGES:
4752
- INLET_TEMPERATURE: <inlet temperature in Celsius for stage>
4853
COMPRESSOR_CHART: <reference to compressor chart model for first stage, must be defined in MODELS or FACILITY_INPUTS>
4954
- INLET_TEMPERATURE: <inlet temperature in Celsius for stage>
5055
COMPRESSOR_CHART: <reference to compressor chart model for second stage, must be defined in MODELS or FACILITY_INPUTS>
5156
- ... and so forth for each stage in the train
52-
POWER_ADJUSTMENT_CONSTANT: <Optional constant MW adjustment added to the model>
5357
MAXIMUM_POWER: <Optional constant MW maximum power the compressor train can require>
5458
~~~~~~~~
5559

@@ -68,11 +72,11 @@ MODELS:
6872
- NAME: <model name>
6973
TYPE: SIMPLIFIED_VARIABLE_SPEED_COMPRESSOR_TRAIN
7074
FLUID_MODEL: <reference to fluid model>
75+
MECHANICAL_EFFICIENCY: <Optional. Default 1.0>
7176
COMPRESSOR_TRAIN:
7277
MAXIMUM_PRESSURE_RATIO_PER_STAGE: <maximum pressure ratio per stage>
7378
COMPRESSOR_CHART: <reference to compressor chart model used for all stages, must be defined in [MODELS] or [FACILITY_INPUTS]>
7479
INLET_TEMPERATURE: <inlet temperature for all stages>
75-
POWER_ADJUSTMENT_CONSTANT: <Optional constant MW adjustment added to the model>
7680
~~~~~~~~
7781

7882
## Examples
@@ -106,6 +110,7 @@ MODELS:
106110
- NAME: simplified_compressor_model
107111
TYPE: SIMPLIFIED_VARIABLE_SPEED_COMPRESSOR_TRAIN
108112
FLUID_MODEL: fluid_model_1
113+
MECHANICAL_EFFICIENCY: 0.95 # Account for 5% mechanical losses in the drivetrain
109114
COMPRESSOR_TRAIN:
110115
STAGES:
111116
- INLET_TEMPERATURE: 30

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

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,11 +24,15 @@ This means that a single speed compressor model needs the following to be define
2424

2525
The following keywords are optional for a single speed compressor model:
2626

27+
- [MECHANICAL_EFFICIENCY](/about/references/MECHANICAL_EFFICIENCY.md) - Mechanical efficiency of the drivetrain (default 1.0)
2728
- [MAXIMUM_DISCHARGE_PRESSURE](/about/references/MAXIMUM_DISCHARGE_PRESSURE.md)
28-
- [POWER_ADJUSTMENT_CONSTANT](/about/references/POWER_ADJUSTMENT_CONSTANT.md)
2929
- [MAXIMUM_POWER](/about/references/MAXIMUM_POWER.md)
3030
- [CALCULATE_MAX_RATE](/about/references/CALCULATE_MAX_RATE.md)
3131

32+
:::warning Deprecated Parameters
33+
The `POWER_ADJUSTMENT_CONSTANT` and `POWER_ADJUSTMENT_FACTOR` parameters are deprecated. Use `MECHANICAL_EFFICIENCY` instead.
34+
:::
35+
3236
The model is defined under the main keyword [MODELS](/about/references/MODELS.md) in the format
3337

3438
## Format
@@ -40,6 +44,7 @@ MODELS:
4044
FLUID_MODEL: <reference to fluid model>
4145
PRESSURE_CONTROL: <method for pressure control, DOWNSTREAM_CHOKE (default), UPSTREAM_CHOKE, , INDIVIDUAL_ASV_PRESSURE, INDIVIDUAL_ASV_RATE or COMMON_ASV>
4246
MAXIMUM_DISCHARGE_PRESSURE: <Maximum discharge pressure in bar (can only use if pressure control is DOWNSTREAM_CHOKE)>
47+
MECHANICAL_EFFICIENCY: <Optional. Mechanical efficiency (0 < η ≤ 1). Default 1.0>
4348
COMPRESSOR_TRAIN:
4449
STAGES:
4550
- INLET_TEMPERATURE: <inlet temperature in Celsius for stage>
@@ -53,7 +58,6 @@ MODELS:
5358
CONTROL_MARGIN_UNIT: <FRACTION or PERCENTAGE, default is PERCENTAGE>
5459
PRESSURE_DROP_AHEAD_OF_STAGE: <Pressure drop before compression stage [in bar]>
5560
- ... and so forth for each stage in the train
56-
POWER_ADJUSTMENT_CONSTANT: <Optional constant MW adjustment added to the model>
5761
MAXIMUM_POWER: <Optional constant MW maximum power the compressor train can require>
5862
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. >
5963
~~~~~~~~

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

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,7 @@ MODELS:
4545
- NAME: <model name>
4646
TYPE: VARIABLE_SPEED_COMPRESSOR_TRAIN
4747
FLUID_MODEL: <reference to fluid model>
48+
MECHANICAL_EFFICIENCY: <Optional. Mechanical efficiency (0 < η ≤ 1). Default 1.0>
4849
COMPRESSOR_TRAIN:
4950
STAGES:
5051
- INLET_TEMPERATURE: <inlet temperature in Celsius for stage>
@@ -58,9 +59,12 @@ MODELS:
5859
PRESSURE_DROP_AHEAD_OF_STAGE: <Pressure drop before compression stage [in bar]>
5960
CONTROL_MARGIN_UNIT: <FRACTION or PERCENTAGE, default is PERCENTAGE>
6061
- ... and so forth for each stage in the train
61-
POWER_ADJUSTMENT_CONSTANT: <Optional constant MW adjustment added to the model>
6262
MAXIMUM_POWER: <Optional constant MW maximum power the compressor train can require>
6363
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. >
6464
PRESSURE_CONTROL: <method for pressure control, DOWNSTREAM_CHOKE (default), UPSTREAM_CHOKE, , INDIVIDUAL_ASV_PRESSURE, INDIVIDUAL_ASV_RATE or COMMON_ASV>
6565
~~~~~~~~
6666

67+
:::warning Deprecated Parameters
68+
The `POWER_ADJUSTMENT_CONSTANT` and `POWER_ADJUSTMENT_FACTOR` parameters are deprecated. Use `MECHANICAL_EFFICIENCY` instead.
69+
:::
70+

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,7 @@ MODELS:
5353
CONTROL_MARGIN_UNIT: <FRACTION or PERCENTAGE, default is PERCENTAGE>
5454
PRESSURE_DROP_AHEAD_OF_STAGE: <Pressure drop before compression stage [in bar]>
5555
- ...
56+
MECHANICAL_EFFICIENCY: <Optional. Mechanical efficiency (0 < η ≤ 1). Default 1.0>
5657
MAXIMUM_POWER: <Optional constant MW maximum power the compressor train can require>
5758
~~~~~~~~
5859

‎docs/docs/about/references/MECHANICAL_EFFICIENCY.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# MECHANICAL_EFFICIENCY
2+
3+
[MODELS](/about/references/MODELS.md) /
4+
[MECHANICAL_EFFICIENCY](/about/references/MECHANICAL_EFFICIENCY.md)
5+
6+
## Description
7+
8+
`MECHANICAL_EFFICIENCY` defines the ratio of useful mechanical work output to the total mechanical work input for the compressor drivetrain. It accounts for power losses in bearings, gearboxes, seals, and couplings.
9+
10+
The mechanical efficiency is used to calculate the shaft power required from the driver:
11+
12+
$$
13+
P_{shaft} = \frac{P_{gas}}{\eta_{mechanical}}
14+
$$
15+
16+
Where:
17+
- $P_{shaft}$ is the shaft power (input from driver) in MW
18+
- $P_{gas}$ is the gas power (thermodynamic work on gas) in MW
19+
- $\eta_{mechanical}$ is the mechanical efficiency (0 < η ≤ 1)
20+
21+
## Format
22+
23+
~~~~yaml
24+
MODELS:
25+
- NAME: <compressor train name>
26+
TYPE: <VARIABLE_SPEED_COMPRESSOR_TRAIN | SINGLE_SPEED_COMPRESSOR_TRAIN | SIMPLIFIED_VARIABLE_SPEED_COMPRESSOR_TRAIN | VARIABLE_SPEED_COMPRESSOR_TRAIN_MULTIPLE_STREAMS_AND_PRESSURES>
27+
MECHANICAL_EFFICIENCY: <value> # Optional, default 1.0
28+
...
29+
~~~~
30+
31+
## Example
32+
33+
~~~~yaml
34+
MODELS:
35+
- NAME: export_compressor
36+
TYPE: VARIABLE_SPEED_COMPRESSOR_TRAIN
37+
MECHANICAL_EFFICIENCY: 0.95 # 95% efficiency, 5% losses
38+
FLUID_MODEL: medium_gas
39+
COMPRESSOR_TRAIN:
40+
STAGES:
41+
- INLET_TEMPERATURE: 30
42+
COMPRESSOR_CHART: compressor_chart_ref
43+
~~~~
44+
45+
## Value Range
46+
47+
| Constraint | Value | Description |
48+
|------------|-------|-------------|
49+
| Minimum | > 0 | Must be positive (exclusive) |
50+
| Maximum | ≤ 1.0 | Cannot exceed 100% efficiency |
51+
| Default | 1.0 | No mechanical losses (ideal drivetrain) |
52+
53+
### Typical Values
54+
55+
| Drive Configuration | Typical Range | Typical Losses | Notes |
56+
|---------------------|---------------|----------------|-------|
57+
| Direct drive | 0.96 - 0.98 | 2-4% | Bearings (1-2%) + seals/couplings (1-2%) |
58+
| With gearbox | 0.93 - 0.96 | 4-7% | Adds gearbox losses (2-3%) |
59+
60+
:::note
61+
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.
62+
:::
63+
64+
## Physical Interpretation
65+
66+
The mechanical efficiency accounts for power losses in the drivetrain between
67+
the driver (motor/turbine) and the compressor, including:
68+
69+
- **Bearing losses**: Friction in shaft support bearings
70+
- **Gearbox losses**: Friction and churning in gear systems (if present)
71+
- **Seal and coupling losses**: Minor friction in auxiliary components
72+
73+
:::note Constant efficiency assumption
74+
In reality, frictional losses scale approximately with the square of rotational speed.
75+
However, eCalc assumes a **constant** mechanical efficiency across all operating points.
76+
Choose a representative value for typical operating conditions, or consult vendor data
77+
for the expected speed range.
78+
:::
79+
80+
## See Also
81+
82+
- [EFFICIENCY](/about/references/EFFICIENCY.md)
83+
- [POLYTROPIC_EFFICIENCY](/about/references/POLYTROPIC_EFFICIENCY.md)
84+
- [Mechanical Efficiency Migration Guide](/about/migration_guides/mechanical_efficiency.md)

‎docs/docs/about/references/POWER_ADJUSTMENT_CONSTANT.md‎

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,10 @@
33
[MODELS](/about/references/MODELS.md) /
44
[POWER_ADJUSTMENT_CONSTANT](/about/references/POWER_ADJUSTMENT_CONSTANT.md)
55

6+
:::warning Deprecated
7+
This parameter is deprecated and will be removed in a future version. Use [MECHANICAL_EFFICIENCY](/about/references/MECHANICAL_EFFICIENCY.md) instead for a physically meaningful way to model mechanical losses.
8+
:::
9+
610
## Description
711
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).
812

@@ -18,6 +22,7 @@ MODELS:
1822

1923
## Example
2024

25+
**Deprecated usage:**
2126
~~~~~yaml
2227
MODELS:
2328
- NAME: simple_compressor
@@ -26,11 +31,4 @@ MODELS:
2631
POWER_ADJUSTMENT_CONSTANT: 10 #MW
2732
~~~~~
2833

29-
~~~~~yaml
30-
MODELS:
31-
- NAME: simple_compressor
32-
TYPE: SIMPLIFIED_VARIABLE_SPEED_COMPRESSOR_TRAIN
33-
...
34-
POWER_ADJUSTMENT_CONSTANT: 10 #MW
35-
POWER_ADJUSTMENT_FACTOR: 1.2
36-
~~~~~
34+
**Recommended migration:** See the [Mechanical Efficiency Migration Guide](/about/migration_guides/mechanical_efficiency.md).

‎docs/docs/about/references/POWER_ADJUSTMENT_FACTOR.md‎

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,10 @@
33
[MODELS](/about/references/MODELS.md) /
44
[POWER_ADJUSTMENT_FACTOR](/about/references/POWER_ADJUSTMENT_FACTOR.md)
55

6+
:::warning Deprecated
7+
This parameter is deprecated and will be removed in a future version. Use [MECHANICAL_EFFICIENCY](/about/references/MECHANICAL_EFFICIENCY.md) instead for a physically meaningful way to model mechanical losses.
8+
:::
9+
610
## Description
711
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).
812

@@ -18,6 +22,7 @@ MODELS:
1822

1923
## Example
2024

25+
**Deprecated usage:**
2126
~~~~~yaml
2227
MODELS:
2328
- NAME: simple_compressor
@@ -26,11 +31,4 @@ MODELS:
2631
POWER_ADJUSTMENT_FACTOR: 1.2
2732
~~~~~
2833

29-
~~~~~yaml
30-
MODELS:
31-
- NAME: simple_compressor
32-
TYPE: SIMPLIFIED_VARIABLE_SPEED_COMPRESSOR_TRAIN
33-
...
34-
POWER_ADJUSTMENT_CONSTANT: 10 #MW
35-
POWER_ADJUSTMENT_FACTOR: 1.2
36-
~~~~~
34+
**Recommended migration:** See the [Mechanical Efficiency Migration Guide](/about/migration_guides/mechanical_efficiency.md).

0 commit comments

Comments
 (0)