turash/models/README.md

# 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

```bash
# 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

```bash
# 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

```go
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

```bash
# 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
```bash
# 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

```bash
# 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.