turash/models

Turash Mathematical Model - Go Implementation

A production-ready Go 1.25 implementation of the Turash mathematical model for consistent financial and environmental impact calculations.

Quick Start

# Install dependencies
make install-deps

# Run tests
make test

# Build the CLI tool
make build

# Run with example parameters
make run-example

# Or run directly
go run ./cmd summary params.yaml

Architecture

The model follows clean architecture principles with separated concerns:

• params/: Parameter loading, validation, and schema
• customer/: Customer adoption and tier distribution calculations
• revenue/: Revenue calculations across 4 distinct paths
• cost/: Cost structure calculations
• impact/: Environmental impact calculations
• market/: Market size constants and calculations
• validator/: Sanity checks and validation rules
• calc.go: Main orchestrator
• cmd/: CLI interface

Usage

CLI Commands

# Calculate and display summary
go run ./cmd summary params.yaml

# Validate parameters only
go run ./cmd validate params.yaml

# Get full JSON output
go run ./cmd calculate params.yaml

# Calculate symbiosis exchange costs
go run ./cmd exchange --type waste_to_resource --value 100000 --volume 1000 --distance 5

# Calculate individual match economics
go run ./cmd match --source-id waste_001 --target-id process_001 --annual-qty 8000 --unit-value 35 --distance 5 --investment 25000

Library Usage

import (
    "github.com/damirmukimov/city_resource_graph/models"
    "github.com/damirmukimov/city_resource_graph/models/params"
)

// Load parameters
p, err := params.LoadFromFile("params.yaml")
if err != nil {
    log.Fatal(err)
}

// Run calculations
result, err := models.Calculate(p)
if err != nil {
    log.Fatal(err)
}

// Access results
for _, year := range result.Years {
    fmt.Printf("Year %d: Revenue=€%.0f, Profit=€%.0f\n",
        year.Year, year.Revenue.Total, year.Profit)
}

Testing

# Run all tests
make test

# Run with coverage
make test-coverage

# Run specific package tests
go test ./revenue -v

Revenue Model

The model calculates revenue across 4 distinct paths:

1. Subscription (SaaS): Tier-based ARR with transaction uplifts
2. Transaction (Marketplace): Introduction fees + marketplace commissions
3. Municipal: City licenses + data licensing
4. Implementation: Paid implementation services

Exchange Cost Calculator

Calculate costs for enabling industrial symbiosis exchanges between businesses:

Symbiosis Types

• Resource Exchanges: waste_to_resource, utility_sharing, energy_cascading, material_recycling
• Infrastructure Sharing: physical_infrastructure, equipment_sharing, logistics_network, utility_infrastructure
• Service Exchanges: knowledge_sharing, workforce_sharing, maintenance_services, procurement_cooperative
• Digital Exchanges: data_sharing, platform_cooperative, iot_network_sharing, software_licenses

Cost Components

• Capital Costs: Setup and integration expenses
• Operating Costs: Ongoing maintenance and coordination
• Platform Fees: 5% transaction fees
• Regulatory Costs: Compliance based on exchange type
• Risk Mitigation: Insurance and liability costs

Example

# Low-cost digital data sharing
./bin/models exchange --type data_sharing --value 50000 --volume 1000 --distance 0 --complexity low --risk low

# Higher-cost physical waste exchange
./bin/models exchange --type waste_to_resource --value 100000 --volume 1000 --distance 5 --complexity medium --risk medium

Match Economics Calculator

Calculate NPV, IRR, payback period, and CO2 impact for individual business-to-business matches:

Key Metrics

• NPV: Net Present Value over 10 years
• IRR: Internal Rate of Return percentage
• Payback Period: Years to recover investment
• Annual Savings: Cost reductions + value creation
• Transportation Costs: Distance-based logistics costs
• CO2 Reduction: Environmental impact per match
• Regulatory Requirements: Permits and approvals needed
• Implementation Complexity: Technical difficulty assessment

Example Output

Individual Match Economic Analysis
==================================
Match ID: match_waste_heat_001_process_heat_001
Annual Exchange: 8000 units @ €35.00/unit
Economic Results:
  Annual Savings: €560,000
  Payback Period: 0.0 years
  NPV (10 years): €3,831,287
  IRR: 2127.8%
Transportation & Impact:
  CO2 Reduction: 4.0 tonnes/year
  Regulatory Requirements: [energy_distribution_license]
✅ Match appears economically viable

Validation Rules

Built-in sanity checks prevent common errors:

• ARPU ranges (300-6000 €/year)
• Implementation density limits
• CO₂/revenue ratio validation
• Heat MWh sanity checks
• Profitability warnings

Dependencies

• Go 1.25+
• gopkg.in/yaml.v3 for YAML support
• github.com/stretchr/testify for testing

Development

# Format code
make fmt

# Run linter (requires golangci-lint)
make lint

# Run all checks
make check

# Clean build artifacts
make clean

Configuration

Parameters are defined in params.yaml with support for yearly values and tier distributions. See the example file for the complete schema.

License

Part of the Turash project documentation and modeling framework.