RES vehicle profiles, engine coefficients, and performance evaluation library
npm install res-profilesRES vehicle profiles, engine coefficients, and performance evaluation library.
This package provides a comprehensive backend for vehicle performance estimation, including:
- Data: Vehicle profiles, engine-family coefficients, modification ontology, and validation datasets
- Core Library: Performance evaluation, modification normalization, VIN-to-profile matching, and calibration utilities
- CLIs: Tools to generate, validate, and calibrate data
``bash`
npm install res-profiles
`typescript
import { evaluate, normalizeMods, matchVinToProfile, loadProfiles } from 'res-profiles';
// Load vehicle profiles
const profiles = await loadProfiles();
// Match VIN to profile
const { profile } = matchVinToProfile({
year: 2019,
make: 'BMW',
model: 'M340i',
engine_code: 'B58B30O1',
drivetrain: 'AWD',
trans: 'AT8',
market: 'USDM'
}, profiles);
// Normalize modification text
const mods = normalizeMods('BM3 Stage 2 E30, catless DP, VRSF IC', 'BMW_B58');
// Evaluate performance
const result = evaluate(profile, mods, {
surface: 'Street',
tires: 'MaxPerf',
tempF: 70,
da_ft: 500
});
console.log(result);
// {
// whp: 425,
// zeroTo60: 3.6,
// quarterET: 12.0,
// trap: 118,
// sustainHint: 'IC upgrade improves sustained performance'
// }
`
field (e.g., "2025-08-RES-v1") for tracking updates and compatibility.CLI Tools
$3
`bash
npm run dev # Demo evaluation with sample data
`$3
`bash
npm run gen:bmw # Generate BMW profiles 2010-2025
`$3
`bash
npm run validate # Validate all profiles against schemas
`$3
`bash
npm run calibrate # Calibrate constants against test data
`Development
$3
- Node.js 18+
- TypeScript 5.3+$3
`bash
npm install
npm run build
npm test
`$3
`
res-profiles/
├─ /src
│ ├─ /types # Zod schemas + TypeScript types
│ ├─ /constants # Performance constants & gain tables
│ ├─ /lib # Core library functions
│ └─ /cli # Command-line tools
├─ /data # Seed data & validation sets
├─ /schemas # JSON Schema definitions
└─ /tests # Vitest test suite
``The evaluation engine uses a physics-based approach:
- Baseline: Crank HP × drivetrain efficiency
- Turbo/SC: Pressure ratio model with efficiency curves
- Fuel System: Ethanol content scaling
- Air Path: Intake, intercooler, and exhaust gains
- Traction: Tire type, surface, and drivetrain effects
Constants (a0-a2, b0-b2, c0-c2) are calibrated against validation data and can be refined using the calibration CLI.
1. Follow TypeScript strict mode and ESLint rules
2. Add tests for new functionality
3. Update schemas when modifying data structures
4. Use semantic versioning for releases
MIT