Simulation Engine API Reference

Overview

The simulation engine provides core calculation capabilities for wastewater treatment process modeling. It supports hydraulic calculations, mass balance, and process performance analysis across multiple flow conditions.

Core Interfaces

StreamData

Represents flow and quality data at a connection point between process units.

Properties

Property	Type	Required	Description
flow	number	Yes	Flow rate in m³/d (default/current flow)
dwf	number	No	Dry Weather Flow in m³/d - base design condition
peakFlow	number	No	Peak flow from network in m³/d
flowConditions	FlowConditionSet	No	Complete flow conditions set for all scenarios
tss	number	No	Total suspended solids in mg/L
cod	number	No	Chemical oxygen demand in mg/L
tkn	number	No	Total Kjeldahl nitrogen in mg/L
tp	number	No	Total phosphorus in mg/L
nh4	number	No	Ammonia nitrogen in mg/L
no2	number	No	Nitrite nitrogen in mg/L (for two-step nitrification)
no3	number	No	Nitrate nitrogen in mg/L
do	number	No	Dissolved oxygen in mg/L
percentDS	number	No	Percent dry solids (%) - for sludge streams

Example

const influent: StreamData = {
  flow: 50000,
  dwf: 50000,
  tss: 250,
  cod: 500,
  tkn: 45,
  nh4: 30,
  tp: 8,
  do: 0.5
};

const effluentQuality: StreamData = {
  flow: 49500,
  tss: 10,
  cod: 40,
  tkn: 5,
  nh4: 1,
  no3: 8,
  tp: 0.5,
  do: 6.5
};

const sludgeStream: StreamData = {
  flow: 500,
  tss: 12000,
  percentDS: 1.2  // 1.2% dry solids
};

Related Types

• FlowConditionSet - Multi-condition flow scenarios
• CalculationEdge - Uses StreamData for edge flow

---

FlowConditionSet

Complete flow condition set for a stream, containing all 6 standard design conditions.

Properties

Property	Type	Description
dwf	number	Dry Weather Flow - base design condition (m³/d)
avgFlow	number	Average daily flow (m³/d)
maxDaily	number	Maximum daily flow - peak day (m³/d)
minInstant	number	Minimum instantaneous flow (L/s)
maxInstant	number	Maximum instantaneous flow (L/s)
peakNetwork	number	Peak flow from network model (L/s)

Example

const flowConditions: FlowConditionSet = {
  dwf: 50000,        // 50,000 m³/d base flow
  avgFlow: 60000,    // 60,000 m³/d annual average
  maxDaily: 90000,   // 90,000 m³/d peak day
  minInstant: 289,   // 289 L/s minimum
  maxInstant: 1736,  // 1,736 L/s maximum (3×DWF)
  peakNetwork: 2315  // 2,315 L/s from network model
};

// Apply to stream
const stream: StreamData = {
  flow: 50000,
  flowConditions: flowConditions,
  tss: 250,
  cod: 500
};

Related Types

• FlowConditionType - Individual condition type enumeration
• FlowConditionMetadata - Display metadata for conditions

---

FlowConditionType

Enumeration of flow condition types for wastewater treatment design.

Values

Value	Description
'DWF'	Dry Weather Flow - base design condition
'avgFlow'	Average daily flow
'maxDaily'	Maximum daily flow (peak day)
'minInstant'	Minimum instantaneous flow
'maxInstant'	Maximum instantaneous flow (3×DWF typical)
'peakNetwork'	Peak flow from network hydraulic model

Example

function getFlowValue(
  conditions: FlowConditionSet,
  type: FlowConditionType
): number {
  switch (type) {
    case 'DWF':
      return conditions.dwf;
    case 'avgFlow':
      return conditions.avgFlow;
    case 'maxDaily':
      return conditions.maxDaily;
    case 'minInstant':
      return conditions.minInstant;
    case 'maxInstant':
      return conditions.maxInstant;
    case 'peakNetwork':
      return conditions.peakNetwork;
  }
}

---

CalculationMode

Calculation mode for process units controlling whether basic fixed-efficiency or advanced mechanistic models are used.

Values

Value	Description
'basic'	Fixed-efficiency calculations (default, backward compatible)
'advanced'	Mechanistic calculations using biokinetic models (ASM1, ASM2d, etc.)

Example

const unitParameters: ProcessUnitParameters = {
  calculationMode: 'advanced',
  volume: 5000,
  doSetpoint: 2.0,
  temperature: 15
};

---

BasicCalculationResult

Result of basic hydraulic calculations for the process flow network.

Properties

Property	Type	Description
flows	Map<string, number>	Edge ID → flow rate (m³/d)
volumes	Map<string, number>	Node ID → volume (m³)
hrt	Map<string, number>	Node ID → hydraulic retention time (hours)
massLoads	Map<string, number>	Edge ID → mass load (kg/d) for TSS
inletFlows	Map<string, number>	Node ID → inlet flow rate (m³/d)
outletFlows	Map<string, number>	Node ID → outlet flow rate (m³/d)
timestamp	Date	Calculation timestamp
success	boolean	Whether calculation completed successfully
errors	string[]	Error messages if any
warnings	string[]	Warning messages if any

Example

interface CalculationEngine {
  calculate(graph: CalculationGraph): BasicCalculationResult;
}

const result = engine.calculate(graph);

if (result.success) {
  console.log(`Flow at edge E1: ${result.flows.get('E1')} m³/d`);
  console.log(`HRT at node N1: ${result.hrt.get('N1')} hours`);
  console.log(`TSS load at edge E2: ${result.massLoads.get('E2')} kg/d`);
} else {
  console.error('Calculation failed:', result.errors);
}

if (result.warnings.length > 0) {
  console.warn('Warnings:', result.warnings);
}

---

CalculationGraph

Complete calculation graph for the wastewater treatment plant.

Properties

Property	Type	Description
nodes	Map<string, CalculationNode>	All nodes in the graph by ID
edges	Map<string, CalculationEdge>	All edges in the graph by ID
calculationOrder	string[]	Topologically sorted node IDs for calculation order
hasCycles	boolean	Whether the graph contains cycles (recycle streams)
tearStreams	string[]	IDs of edges that are tear streams for recycle convergence

Example

// Build calculation graph
const graph: CalculationGraph = {
  nodes: new Map([
    ['N1', influentNode],
    ['N2', primaryNode],
    ['N3', aerationNode],
    ['N4', clarifierNode]
  ]),
  edges: new Map([
    ['E1', { id: 'E1', sourceId: 'N1', targetId: 'N2', streamData: { flow: 50000 } }],
    ['E2', { id: 'E2', sourceId: 'N2', targetId: 'N3', streamData: { flow: 50000 } }],
    ['E3', { id: 'E3', sourceId: 'N3', targetId: 'N4', streamData: { flow: 50000 } }]
  ]),
  calculationOrder: ['N1', 'N2', 'N3', 'N4'],
  hasCycles: false,
  tearStreams: []
};

// Process in topological order
for (const nodeId of graph.calculationOrder) {
  const node = graph.nodes.get(nodeId);
  // Perform calculations...
}

Related Types

• CalculationNode - Node structure
• CalculationEdge - Edge structure

---

CalculationNode

Node in the calculation graph representing a process unit.

Properties

Property	Type	Description
id	string	Unique node ID
name	string	Display name
unitType	ProcessUnitType	Process unit type
parameters	ProcessUnitParameters	Unit parameters
upstreamNodes	string[]	IDs of upstream nodes
downstreamNodes	string[]	IDs of downstream nodes
inlet	StreamData	undefined
outlets	StreamData[]	Outlet stream data (multiple for splitters)
displayValues	DisplayValue[]	Display values for UI

Example

const aerationNode: CalculationNode = {
  id: 'aeration-1',
  name: 'Aeration Tank',
  unitType: 'aerobicZone',
  parameters: {
    volume: 5000,
    doSetpoint: 2.0,
    temperature: 15
  },
  upstreamNodes: ['primary-1'],
  downstreamNodes: ['clarifier-1'],
  inlet: {
    flow: 50000,
    tss: 150,
    cod: 300
  },
  outlets: [{
    flow: 50000,
    tss: 3000,  // MLSS
    do: 2.0
  }],
  displayValues: [
    { label: 'Volume', value: 5000, unit: 'm³', position: 'top' },
    { label: 'DO', value: 2.0, unit: 'mg/L', position: 'inside' }
  ]
};

---

CalculationEdge

Edge in the calculation graph representing a process connection.

Properties

Property	Type	Description
id	string	Unique edge ID
sourceId	string	Source node ID
targetId	string	Target node ID
sourceHandle	string	undefined
targetHandle	string	undefined
streamData	StreamData	Stream data flowing through this edge
label	string	undefined

Example

const rasEdge: CalculationEdge = {
  id: 'edge-ras',
  sourceId: 'clarifier-1',
  targetId: 'aeration-1',
  sourceHandle: 'underflow',
  targetHandle: 'recycle',
  streamData: {
    flow: 50000,  // 1:1 RAS ratio
    tss: 12000,   // RAS solids
    do: 0.5
  },
  label: 'RAS'
};

---

DisplayValue

Display value to show on canvas nodes/edges for visual feedback.

Properties

Property	Type	Description
label	string	Short label for the value
value	string | number	Formatted value string or number
unit	string	Unit of measurement
position	string	undefined
color	string	undefined

Example

const displayValues: DisplayValue[] = [
  {
    label: 'Flow',
    value: 50000,
    unit: 'm³/d',
    position: 'top'
  },
  {
    label: 'DO',
    value: 2.0,
    unit: 'mg/L',
    position: 'inside',
    color: '#00ff00'
  },
  {
    label: 'MLSS',
    value: 3000,
    unit: 'mg/L',
    position: 'bottom'
  }
];

---

ProcessUnitParameters

Configuration parameters extracted from node data for calculations.

See Process Units API for complete documentation of all parameters.

---

Equipment Configuration Types

EquipmentStatus

Equipment status in the project indicating project scope.

Values

Value	Description
'existing'	Equipment already installed and operational
'new'	Equipment to be installed as part of project
'to-be-removed'	Equipment to be demolished/removed
'future'	Equipment for future phases

---

ProcessUnitConfig

Extended process unit configuration supporting quantity, duty/standby, and status.

Properties

Property	Type	Description
quantity	number	Number of parallel identical units (e.g., 3 for "3 PSTs")
dutyConfig	DutyStandbyConfig	undefined
status	EquipmentStatus	Equipment status in project
puNumber	string	undefined
puRange	string	undefined
puNumberOverride	string	undefined

Example

const pumpConfig: ProcessUnitConfig = {
  quantity: 3,
  dutyConfig: {
    duty: 2,
    standby: 1,
    label: '2D+1S'
  },
  status: 'new',
  puNumber: 'PU5',
  puRange: 'PU5-PU7'
};

---

DutyStandbyConfig

Duty/standby configuration for parallel units.

Properties

Property	Type	Description
duty	number	Number of duty units (normally operating)
standby	number	Number of standby units (backup)
assist	number	undefined
label	string	undefined

Example

const config: DutyStandbyConfig = {
  duty: 2,
  standby: 1,
  label: '2D+1S'
};

// With assist pump
const configWithAssist: DutyStandbyConfig = {
  duty: 2,
  standby: 1,
  assist: 1,
  label: '2D+1S+1A'
};

---

Implementation Notes

Flow Calculations

1. Multi-condition Support: StreamData supports multiple flow conditions for comprehensive design analysis
2. Default Flow: The flow property is the primary/active flow condition
3. Optional Conditions: Individual flow conditions (dwf, peakFlow) or complete FlowConditionSet can be provided

Calculation Order

1. Topological Sort: Nodes are calculated in topological order from the calculationOrder array
2. Recycle Handling: Graphs with cycles use tear streams for iterative convergence
3. Convergence: Recycle loops iterate until mass balance closes within tolerance

Units Consistency

All calculations use consistent SI units:

• Flow: m³/d (daily) or L/s (instantaneous)
• Concentration: mg/L
• Mass: kg/d
• Volume: m³
• Time: hours (HRT), days (SRT)

Error Handling

Calculations return success/failure status with:

• success: boolean indicating overall success
• errors: array of error messages for failures
• warnings: array of warning messages for non-critical issues