MachSysS - Machinery System Structure

MachSysS provides Protocol Buffer definitions, data structures, and conversion utilities for the FEEMS ecosystem. It enables standardized data exchange, serialization, and interoperability across different tools and programming languages.

Features

🔄 Data Exchange

• Protocol Buffer Schemas: Well-defined data structures for machinery systems
• Language Independence: Use in Python, C++, Java, Go, and more
• Version Control Friendly: Text-based proto definitions
• Compact Binary Format: Efficient storage and transmission

🔧 Conversion Utilities

• FEEMS ↔ Protobuf: Bidirectional conversion between FEEMS objects and protobuf messages
• Result Serialization: Save simulation results for analysis and reporting
• System Configuration: Load/save complete system configurations
• Time-Series Data: Handle time-series results with pandas integration

📊 Data Structures

• System Configuration: Complete machinery system layout
• Component Specifications: Engines, generators, converters, loads
• Simulation Results: Fuel consumption, emissions, energy flows
• Time-Series Profiles: Operational data over time

Installation

From PyPI

pip install MachSysS

From Source (Developers)

# Clone repository
git clone https://github.com/SINTEF/FEEMS.git
cd FEEMS

# Install with uv (recommended)
uv sync

# Or with pip
pip install -e machinery-system-structure/

Quick Start

Save a FEEMS System to Protobuf

from feems.system_model import ElectricPowerSystem
from MachSysS.convert_to_protobuf import convert_electric_system_to_protobuf_machinery_system

# Create or load a FEEMS system
system = ElectricPowerSystem(...)

# Convert to protobuf
system_pb = convert_electric_system_to_protobuf_machinery_system(system)

# Save to file
with open("system_config.pb", "wb") as f:
    f.write(system_pb.SerializeToString())

Load a System from Protobuf

from MachSysS.system_structure_pb2 import MachinerySystem
from MachSysS.convert_to_feems import convert_proto_propulsion_system_to_feems

# Load from file
with open("system_config.pb", "rb") as f:
    system_pb = MachinerySystem()
    system_pb.ParseFromString(f.read())

# Convert to FEEMS system
feems_system = convert_proto_propulsion_system_to_feems(system_pb)

# Use with FEEMS
feems_system.do_power_balance_calculation()

Save Simulation Results

from MachSysS.convert_feems_result_to_proto import convert_feems_result_to_proto

# Run simulation
result = system.get_fuel_energy_consumption_running_time()

# Convert results to protobuf
result_pb = convert_feems_result_to_proto(result, system)

# Save to file
with open("simulation_results.pb", "wb") as f:
    f.write(result_pb.SerializeToString())

Convert Results to Pandas DataFrames

from MachSysS.convert_proto_timeseries import convert_proto_power_timeseries_to_df

# Load results
from MachSysS.feems_result_pb2 import FeemsResult
with open("simulation_results.pb", "rb") as f:
    result_pb = FeemsResult()
    result_pb.ParseFromString(f.read())

# Convert to DataFrame
df = convert_proto_power_timeseries_to_df(result_pb.power_timeseries)

# Analyze with pandas
print(df.describe())
df.plot()

Protocol Buffer Schemas

System Structure (system_structure.proto)

Defines the complete machinery system configuration:

message MachinerySystem {
  string name = 1;
  repeated Component components = 2;
  repeated Connection connections = 3;
  repeated Switchboard switchboards = 4;
  repeated BusTieBreaker bus_tie_breakers = 5;
}

message Component {
  string id = 1;
  string name = 2;
  ComponentType type = 3;
  double rated_power_kw = 4;
  double rated_speed_rpm = 5;
  PerformanceCurve performance_curve = 6;
  // ...
}

Simulation Results (feems_result.proto)

Stores simulation outputs:

message FeemsResult {
  string system_id = 1;
  double duration_s = 2;
  FuelConsumption total_fuel_consumption = 3;
  Emissions total_emissions = 4;
  EnergyConsumption energy_consumption = 5;
  repeated ComponentResult component_results = 6;
  PowerTimeSeries power_timeseries = 7;
}

Time-Series Data (gymir_result.proto)

Alternative format for time-series results:

message PowerTimeSeries {
  repeated double timestamp_s = 1;
  map<string, PowerProfile> component_powers = 2;
}

message PowerProfile {
  repeated double power_kw = 1;
  repeated double efficiency = 2;
}

Conversion API

System Conversion

FEEMS → Protobuf

from MachSysS.convert_to_protobuf import (
    convert_electric_system_to_protobuf_machinery_system,
    convert_component_to_protobuf
)

# Convert complete system
system_pb = convert_electric_system_to_protobuf_machinery_system(feems_system)

# Convert individual component
component_pb = convert_component_to_protobuf(genset)

Protobuf → FEEMS

from MachSysS.convert_to_feems import (
    convert_proto_propulsion_system_to_feems,
    convert_proto_component_to_feems
)

# Convert complete system
feems_system = convert_proto_propulsion_system_to_feems(system_pb)

# Convert individual component
component = convert_proto_component_to_feems(component_pb)

Results Conversion

from MachSysS.convert_feems_result_to_proto import (
    convert_feems_result_to_proto,
    convert_fuel_consumption_to_proto,
    convert_emissions_to_proto
)

# Convert complete result
result_pb = convert_feems_result_to_proto(feems_result, system)

# Convert individual metrics
fuel_pb = convert_fuel_consumption_to_proto(fuel_consumption)
emissions_pb = convert_emissions_to_proto(emissions)

Time-Series Conversion

from MachSysS.convert_proto_timeseries import (
    convert_proto_power_timeseries_to_df,
    convert_df_to_proto_power_timeseries
)

# Protobuf → DataFrame
df = convert_proto_power_timeseries_to_df(power_timeseries_pb)

# DataFrame → Protobuf
power_timeseries_pb = convert_df_to_proto_power_timeseries(df)

Use Cases

1. Data Archiving

• Save system configurations for version control
• Archive simulation results for compliance
• Store reference designs

2. Tool Integration

• Exchange data with other simulation tools
• Import/export to CAD software
• Connect to databases

3. API Development

• Build REST APIs with protobuf serialization
• gRPC services for remote simulation
• Microservices architecture

4. Cross-Language Support

• Python simulation, C++ visualization
• Java backend, Python frontend
• Go microservices with Python analysis

5. Reporting

• Generate standardized reports
• Export to business intelligence tools
• Regulatory compliance submissions

Package Structure

machinery-system-structure/
├── MachSysS/
│   ├── __init__.py
│   ├── system_structure_pb2.py     # Generated from .proto
│   ├── system_structure_pb2.pyi    # Type stubs
│   ├── feems_result_pb2.py         # Generated from .proto
│   ├── gymir_result_pb2.py         # Generated from .proto
│   ├── convert_to_protobuf.py      # FEEMS → Protobuf
│   ├── convert_to_feems.py         # Protobuf → FEEMS
│   ├── convert_feems_result_to_proto.py
│   └── convert_proto_timeseries.py
├── proto/
│   ├── system_structure.proto
│   ├── feems_result.proto
│   └── gymir_result.proto
├── tests/
├── compile_proto.sh                 # Protobuf compilation script
└── README.md

Development

Prerequisites

• Python ≥ 3.10
• Protocol Buffer compiler (protoc) for regenerating Python bindings

Install protoc

macOS:

brew install protobuf

Ubuntu/Debian:

apt-get install protobuf-compiler

Windows: Download from GitHub Releases

Workspace Setup

# Clone and sync
git clone https://github.com/SINTEF/FEEMS.git
cd FEEMS
uv sync

Regenerating Protobuf Files

When you modify .proto files:

cd machinery-system-structure
./compile_proto.sh

This script:

1. Compiles .proto files to Python
2. Generates type stubs (.pyi files)
3. Fixes imports for relative module references

Manual compilation:

cd machinery-system-structure
protoc -I=proto --python_out=MachSysS proto/*.proto --pyi_out=MachSysS

Running Tests

# All tests
uv run pytest machinery-system-structure/tests/

# Specific test file
uv run pytest machinery-system-structure/tests/test_convert_to_protobuf.py

# With coverage
uv run pytest --cov=MachSysS machinery-system-structure/tests/

Code Quality

# Linting
uv run ruff check machinery-system-structure/

# Formatting
uv run ruff format machinery-system-structure/

Requirements

• Python ≥ 3.10
• protobuf >= 5.29.6, < 6
• feems (for conversion utilities)
• pandas (for time-series conversion)

Related Packages

• feems: Core FEEMS library for marine power system modeling
• RunFeemsSim: High-level simulation interface with PMS logic

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

When adding new proto definitions:

1. Edit .proto files in proto/
2. Run ./compile_proto.sh
3. Add conversion utilities in MachSysS/
4. Write tests in tests/
5. Update documentation

License

Licensed under the Apache License 2.0 - see LICENSE file for details.

Citation

@software{machsyss2024,
  title = {MachSysS: Machinery System Structure},
  author = {Yum, Kevin Koosup and contributors},
  year = {2024},
  url = {https://github.com/SINTEF/FEEMS}
}

Support

• Issues: GitHub Issues
• Documentation: https://keviny.github.io/MachSysS/
• Email: kevinkoosup.yum@sintef.no

Acknowledgments

Developed by SINTEF Ocean as part of the FEEMS ecosystem for standardized marine power system data exchange.