Mechanical Design Database and Data Sources

Overview

NeqSim supports loading mechanical design parameters from various data sources including databases and CSV files. This allows organizations to maintain centralized repositories of design data, material properties, and company-specific standards.

Data Source Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    MechanicalDesignDataSource                    │
│                         (Interface)                              │
├─────────────────────────────────────────────────────────────────┤
│                              │                                   │
│         ┌────────────────────┼────────────────────┐             │
│         ▼                    ▼                    ▼             │
│ ┌───────────────┐  ┌─────────────────┐  ┌──────────────────┐   │
│ │ Database      │  │ CSV Data        │  │ Standard-Based   │   │
│ │ DataSource    │  │ Source          │  │ CSV DataSource   │   │
│ └───────────────┘  └─────────────────┘  └──────────────────┘   │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

MechanicalDesignDataSource Interface

The core interface for all design data sources:

public interface MechanicalDesignDataSource {
    
    /**
     * Get a design parameter value.
     * @param category Parameter category (e.g., "material", "safety_factor")
     * @param parameterName Parameter name (e.g., "tensile_strength")
     * @param equipmentType Equipment type filter
     * @return Parameter value as double
     */
    double getParameter(String category, String parameterName, String equipmentType);
    
    /**
     * Get a string property.
     */
    String getProperty(String category, String propertyName, String equipmentType);
    
    /**
     * Check if data source is available.
     */
    boolean isAvailable();
    
    /**
     * Get the standard type this data source provides data for.
     */
    StandardType getStandardType();
}

Database Data Source

Configuration

The DatabaseMechanicalDesignDataSource connects to the NeqSim database:

import neqsim.process.mechanicaldesign.data.DatabaseMechanicalDesignDataSource;

// Create database source (uses default neqsim database)
DatabaseMechanicalDesignDataSource dbSource = new DatabaseMechanicalDesignDataSource();

// Or specify connection
DatabaseMechanicalDesignDataSource dbSource = new DatabaseMechanicalDesignDataSource(
    "jdbc:derby:neqsimthermodatabase",
    "TechnicalRequirements_Process"
);

Database Schema

The primary table TechnicalRequirements_Process stores design parameters:

CREATE TABLE TechnicalRequirements_Process (
    ID              INTEGER PRIMARY KEY,
    COMPANY         VARCHAR(50),
    CATEGORY        VARCHAR(100),
    PARAMETER_NAME  VARCHAR(100),
    EQUIPMENT_TYPE  VARCHAR(50),
    VALUE_NUMERIC   DOUBLE,
    VALUE_TEXT      VARCHAR(255),
    UNIT            VARCHAR(20),
    STANDARD_CODE   VARCHAR(20),
    VERSION         VARCHAR(10),
    NOTES           VARCHAR(500)
);

-- Example data
INSERT INTO TechnicalRequirements_Process VALUES
(1, 'Equinor', 'safety_factor', 'pressure_margin', 'separator', 1.10, NULL, '-', 'NORSOK-P002', 'Rev3', NULL),
(2, 'Equinor', 'material', 'min_wall_thickness', 'pressure_vessel', 6.0, NULL, 'mm', 'ASME-VIII-1', '2023', NULL),
(3, 'Equinor', 'sizing', 'liquid_retention_time', 'separator', 180, NULL, 's', 'NORSOK-P002', 'Rev3', 'Minimum 3 minutes');

Querying the Database

// Get numeric parameter
double pressureMargin = dbSource.getParameter("safety_factor", "pressure_margin", "separator");

// Get text property
String material = dbSource.getProperty("material", "default_plate_grade", "pressure_vessel");

// Check availability
if (dbSource.isAvailable()) {
    // Use database source
}

CSV Data Source

Basic CSV Format

Create CSV files for design parameters:

File: designdata/company_standards.csv

category,parameter_name,equipment_type,value_numeric,value_text,unit,standard_code
safety_factor,pressure_margin,separator,1.10,,−,NORSOK-P002
safety_factor,temperature_margin,all,25.0,,C,NORSOK-P001
material,default_plate_grade,pressure_vessel,,SA-516-70,,ASTM-A516
sizing,liquid_retention_time,separator,180.0,,s,NORSOK-P002
sizing,gas_velocity_factor,scrubber,0.07,,-,API-12J

Using CSV Data Source

import neqsim.process.mechanicaldesign.data.StandardBasedCsvDataSource;
import neqsim.process.mechanicaldesign.designstandards.StandardType;

// Load from file path
StandardBasedCsvDataSource csvSource = new StandardBasedCsvDataSource(
    "path/to/company_standards.csv",
    StandardType.NORSOK_P002
);

// Load from classpath resource
StandardBasedCsvDataSource csvSource = new StandardBasedCsvDataSource(
    "designdata/equinor_standards.csv",
    StandardType.NORSOK_P002
);

// Get parameters
double retentionTime = csvSource.getParameter("sizing", "liquid_retention_time", "separator");

Standard-Based CSV Structure

For standards-specific data, use the enhanced format:

File: designdata/asme_viii_parameters.csv

standard_code,category,parameter_name,equipment_type,value,unit,version,notes
ASME-VIII-1,joint_efficiency,full_radiograph,all,1.0,-,2023,Category A and B joints
ASME-VIII-1,joint_efficiency,spot_radiograph,all,0.85,-,2023,Category A and B joints
ASME-VIII-1,joint_efficiency,no_radiograph,all,0.70,-,2023,Category A and B joints
ASME-VIII-1,material,min_tensile_strength,SA-516-70,485,MPa,2023,Grade 70
ASME-VIII-1,material,allowable_stress,SA-516-70,138,MPa,2023,At 100°C

Registering Data Sources

With MechanicalDesign

import neqsim.process.mechanicaldesign.MechanicalDesign;

MechanicalDesign mechDesign = separator.getMechanicalDesign();

// Add database source
mechDesign.addDataSource(new DatabaseMechanicalDesignDataSource());

// Add CSV source
mechDesign.addDataSource(new StandardBasedCsvDataSource(
    "designdata/norsok_p002.csv",
    StandardType.NORSOK_P002
));

// Data sources are queried in order added (first match wins)

With SystemMechanicalDesign

import neqsim.process.mechanicaldesign.SystemMechanicalDesign;

SystemMechanicalDesign sysMech = new SystemMechanicalDesign(process);

// Configure data sources for entire system
sysMech.addDataSource(new DatabaseMechanicalDesignDataSource());
sysMech.addDataSource(new StandardBasedCsvDataSource("company_stds.csv", StandardType.NORSOK_P001));

Default Data Location

NeqSim looks for design data in these locations:

  1. Classpath resources: src/main/resources/designdata/
  2. Working directory: ./designdata/
  3. User home: ~/.neqsim/designdata/

Provided Default Files

File Description
asme_viii_materials.csv ASME Section VIII material allowables
norsok_p002_sizing.csv NORSOK P-002 sizing parameters
api_617_compressors.csv API 617 compressor requirements
dnv_os_f101_pipeline.csv DNV pipeline design factors

Creating Custom Data Sources

Implement the MechanicalDesignDataSource interface:

public class MyCompanyDataSource implements MechanicalDesignDataSource {
    
    private Map<String, Double> parameters = new HashMap<>();
    
    @Override
    public double getParameter(String category, String parameterName, String equipmentType) {
        String key = category + ":" + parameterName + ":" + equipmentType;
        return parameters.getOrDefault(key, Double.NaN);
    }
    
    @Override
    public String getProperty(String category, String propertyName, String equipmentType) {
        // Implementation
        return null;
    }
    
    @Override
    public boolean isAvailable() {
        return true;
    }
    
    @Override
    public StandardType getStandardType() {
        return StandardType.NORSOK_P001;
    }
}

Data Validation

NeqSim validates data source values:

import neqsim.process.mechanicaldesign.data.DataSourceValidator;

// Validate a data source
DataSourceValidator validator = new DataSourceValidator();
List<String> errors = validator.validate(csvSource);

if (!errors.isEmpty()) {
    for (String error : errors) {
        System.err.println("Validation error: " + error);
    }
}

Best Practices

1. Version Control Your Data

Keep CSV files in version control alongside your simulations:

project/
├── simulations/
│   └── hp_separator_sizing.java
├── designdata/
│   ├── project_standards.csv
│   └── material_data.csv
└── README.md

2. Use Standard Codes Consistently

Always reference standards by their StandardType code:

# Good
standard_code,category,parameter
NORSOK-P002,sizing,liquid_retention

# Avoid
standard_code,category,parameter  
NORSOK P-002,sizing,liquid_retention
Norsok-P002,sizing,liquid_retention

3. Document Units

Always include units in your data:

parameter_name,value,unit
min_wall_thickness,6.0,mm
design_pressure,50.0,barg
temperature_margin,25.0,C

4. Layer Data Sources

Use multiple sources with appropriate priority:

// Priority order: company-specific → project-specific → defaults
mechDesign.addDataSource(new CsvDataSource("company_standards.csv"));  // 1st priority
mechDesign.addDataSource(new CsvDataSource("project_overrides.csv"));  // 2nd priority
mechDesign.addDataSource(new DatabaseMechanicalDesignDataSource());    // 3rd priority (fallback)

See Also