Mass Balance API Reference

Overview

The Mass Balance API provides integrated mass balance calculations for stream-by-stream process analysis. It combines hydraulic calculations with water quality transformations to produce comprehensive mass balances following UK water industry standards.

Core Types

MassBalanceScenarioType

Scenario type for mass balance analysis.

Values

Value	Description
`'Current'`	Current/existing conditions
`'Future'`	Future design conditions
`'AsBuilt'`	As-built conditions post-construction
`'Commissioning'`	Commissioning phase conditions
`'Event'`	Storm event or special operating conditions

FlowConditionType

Flow condition type for mass balance.

Values

Value	Description
`'DWF'`	Dry Weather Flow
`'ADF'`	Average Daily Flow
`'FFT'`	Full Flow to Treatment (Maximum Daily)
`'MinInstant'`	Minimum Instantaneous Flow
`'MaxInstant'`	Maximum Instantaneous Flow
`'Peak'`	Peak Flow from Network

StreamType

Stream type classification.

Values

Value	Description
`'mainProcess'`	Main process flow stream
`'stormFlow'`	Storm/wet weather flow
`'sludge'`	Sludge stream
`'recirculation'`	Recycle/recirculation stream
`'chemical'`	Chemical dosing stream
`'liquor'`	Return liquor stream

Stream Data Structures

StreamFlowConditions

Flow conditions for a stream across all design scenarios.

Properties

Property	Type	Description
dwf	number	Dry weather flow (m³/d)
average	number	Average daily flow (m³/d)
fft	number	Full flow to treatment (m³/d)
minInstantaneous	number	undefined
maxInstantaneous	number	undefined
peakFromNetwork	number	undefined

Example

typescript

const streamFlows: StreamFlowConditions = {
  dwf: 50000,
  average: 60000,
  fft: 90000,
  minInstantaneous: 289,      // 289 L/s
  maxInstantaneous: 1736,     // 1,736 L/s (3×DWF)
  peakFromNetwork: 2315       // 2,315 L/s from network model
};

StreamMassLoads

Mass loads for a stream in kg/d.

Properties

Property	Type	Description
tss	number	Suspended solids load (kg/d)
bod	number	BOD load (kg/d)
ammN	number	Ammonia nitrogen load (kg/d)
tp	number	Total phosphorus load (kg/d)
cod	number	undefined
tkn	number	undefined

Example

typescript

const influentLoads: StreamMassLoads = {
  tss: 12500,      // 12.5 tonnes/d
  bod: 10000,      // 10 tonnes/d
  ammN: 2250,      // 2.25 tonnes/d
  tp: 400,         // 400 kg/d
  cod: 25000,      // 25 tonnes/d
  tkn: 2700        // 2.7 tonnes/d
};

// Calculate from flow and concentration
function calculateMassLoad(
  flow: number,        // m³/d
  concentration: number // mg/L
): number {
  return (flow * concentration) / 1000;  // kg/d
}

const tssLoad = calculateMassLoad(50000, 250);  // 12,500 kg/d

StreamConcentrations

Concentrations for a stream in mg/L.

Properties

Property	Type	Description
tss	number	Suspended solids concentration (mg/L)
bod	number	BOD concentration (mg/L)
ammN	number	Ammonia nitrogen concentration (mg/L)
tp	number	Total phosphorus concentration (mg/L)
cod	number	undefined
percentDS	number	undefined

Example

typescript

const influentConc: StreamConcentrations = {
  tss: 250,
  bod: 200,
  ammN: 45,
  tp: 8,
  cod: 500
};

const sludgeConc: StreamConcentrations = {
  tss: 12000,
  bod: 8000,
  ammN: 600,
  tp: 200,
  percentDS: 1.2    // 1.2% dry solids
};

// Calculate concentration from mass load and flow
function calculateConcentration(
  massLoad: number,   // kg/d
  flow: number        // m³/d
): number {
  if (flow < 0.001) return 0;
  return (massLoad * 1000) / flow;  // mg/L
}

StreamBalance

Complete stream balance data for a single stream.

Properties

Property	Type	Description
streamId	string	Stream ID (F1, F2, etc.)
streamNumber	number	Stream number (1, 2, 3...)
description	string	Stream description
sourceUnit	string	Source process unit
targetUnit	string	Target process unit
streamType	StreamType	Stream type classification
flows	StreamFlowConditions	Flow conditions
massLoads	StreamMassLoads	Mass loads (kg/d)
concentrations	StreamConcentrations	Concentrations at average flow (mg/L)
isSludgeStream	boolean	Whether this is a sludge stream
notes	string	undefined

Example

typescript

const stream1: StreamBalance = {
  streamId: 'F1',
  streamNumber: 1,
  description: 'Raw Influent',
  sourceUnit: 'Inlet Works',
  targetUnit: 'Primary Clarifiers',
  streamType: 'mainProcess',
  flows: {
    dwf: 50000,
    average: 60000,
    fft: 90000,
    minInstantaneous: 289,
    maxInstantaneous: 1736
  },
  massLoads: {
    tss: 12500,
    bod: 10000,
    ammN: 2250,
    tp: 400
  },
  concentrations: {
    tss: 250,
    bod: 200,
    ammN: 45,
    tp: 8
  },
  isSludgeStream: false,
  notes: 'Design basis from flow survey 2024'
};

const rasStream: StreamBalance = {
  streamId: 'F8',
  streamNumber: 8,
  description: 'Return Activated Sludge',
  sourceUnit: 'Secondary Clarifiers',
  targetUnit: 'Aeration Tanks',
  streamType: 'recirculation',
  flows: {
    dwf: 50000,
    average: 60000,
    fft: 90000
  },
  massLoads: {
    tss: 600000,    // 600 tonnes/d MLSS recirculation
    bod: 0,
    ammN: 0,
    tp: 0
  },
  concentrations: {
    tss: 10000,     // 10,000 mg/L RAS solids
    bod: 0,
    ammN: 0,
    tp: 0
  },
  isSludgeStream: true,
  notes: '1:1 RAS ratio at average flow'
};

Process Unit Data Structures

ProcessUnitBalance

Process unit configuration for mass balance.

Properties

Property	Type	Description
puId	string	Process unit ID (PU1, PU2, etc.)
puNumber	number	Process unit number
name	string	Process unit name
unitType	ProcessUnitTypeForBalance	Process unit type
quantity	number	Number of units
dutyConfig	DutyConfig	undefined
status	EquipmentStatus	Unit status ('existing', 'new', 'to-be-removed')
inletStreams	string[]	Inlet stream IDs
outletStreams	string[]	Outlet stream IDs
removalEfficiencies	RemovalEfficiencies	undefined

Duty Configuration

Property	Type	Description
duty	number	Number of duty units
assist	number	undefined
standby	number	undefined
label	string	Configuration label (e.g., "2D+1S")

Removal Efficiencies

Property	Type	Description
bod	number	undefined
tss	number	undefined
ammN	number	undefined
tp	number	undefined

Example

typescript

const primaryClarifiers: ProcessUnitBalance = {
  puId: 'PU1',
  puNumber: 1,
  name: 'Primary Clarifiers',
  unitType: 'PST',
  quantity: 3,
  dutyConfig: {
    duty: 2,
    standby: 1,
    label: '2D+1S'
  },
  status: 'existing',
  inletStreams: ['F1'],
  outletStreams: ['F2', 'F3'],
  removalEfficiencies: {
    bod: 0.35,      // 35% BOD removal
    tss: 0.60,      // 60% TSS removal
    ammN: 0.0,      // No ammonia removal
    tp: 0.10        // 10% TP removal (settling)
  }
};

const aerationTanks: ProcessUnitBalance = {
  puId: 'PU3',
  puNumber: 3,
  name: 'Aeration Tanks',
  unitType: 'ASP',
  quantity: 4,
  dutyConfig: {
    duty: 4,
    label: '4D'
  },
  status: 'existing',
  inletStreams: ['F2', 'F8'],
  outletStreams: ['F4'],
  removalEfficiencies: {
    bod: 0.95,      // 95% BOD removal
    tss: 0.0,       // TSS generated (MLSS)
    ammN: 0.90,     // 90% ammonia removal
    tp: 0.30        // 30% TP removal (luxury uptake)
  }
};

Balance Verification

BalanceCheck

Balance check result for mass conservation.

Properties

Property	Type	Description
parameter	BalanceParameter	Parameter being checked
location	string	Process unit or junction
totalIn	number	Total input
totalOut	number	Total output
difference	number	Difference (out - in)
percentDifference	number	Percentage difference
balanced	boolean	Whether balance closes within tolerance
notes	string	undefined

Balance Parameters

'Flow' | 'BOD' | 'TSS' | 'AmmN' | 'TP'

Example

typescript

const flowBalance: BalanceCheck = {
  parameter: 'Flow',
  location: 'Primary Clarifiers',
  totalIn: 60000,        // m³/d
  totalOut: 60000,       // m³/d
  difference: 0,
  percentDifference: 0,
  balanced: true
};

const bodBalance: BalanceCheck = {
  parameter: 'BOD',
  location: 'Primary Clarifiers',
  totalIn: 12000,        // kg/d in
  totalOut: 8200,        // kg/d out (7800 effluent + 400 sludge)
  difference: -3800,     // 3800 kg/d removed
  percentDifference: -31.7,
  balanced: true,
  notes: '35% BOD removal, rest to sludge'
};

// Check if balance closes
function isBalanced(check: BalanceCheck, tolerance: number = 5): boolean {
  return Math.abs(check.percentDifference) <= tolerance;
}

Complete Mass Balance

ProcessCalcMassBalance

Complete process calculation mass balance.

Properties

Property	Type	Description
scenarioName	string	Scenario name
scenarioType	MassBalanceScenarioType	Scenario type
description	string	undefined
generatedAt	Date	Generation timestamp
streams	StreamBalance[]	All streams in the process
processUnits	ProcessUnitBalance[]	All process units
balanceChecks	BalanceCheck[]	Balance check results
notes	StreamNote[]	Stream notes and annotations
balanceStatus	BalanceStatus	'Balanced', 'Unbalanced', 'Warning'
summary	MassBalanceSummary	Summary statistics

Example

typescript

const massBalance: ProcessCalcMassBalance = {
  scenarioName: 'Future Upgrade - Average Flow',
  scenarioType: 'Future',
  description: 'Future conditions after Phase 2 upgrades',
  generatedAt: new Date(),
  streams: [stream1, stream2, stream3],
  processUnits: [primaryClarifiers, aerationTanks],
  balanceChecks: [flowBalance, bodBalance],
  notes: [
    {
      streamId: 'F1',
      note: 'Design flows from 2024 flow survey',
      type: 'assumption'
    }
  ],
  balanceStatus: 'Balanced',
  summary: {
    totalInletFlow: 60000,
    totalEffluentFlow: 59500,
    totalSludgeProduction: 2400,
    overallBODRemoval: 95,
    overallTSSRemoval: 96,
    overallAmmNRemoval: 90,
    overallPRemoval: 75,
    numberOfProcessUnits: 12,
    numberOfStreams: 24
  }
};

MassBalanceSummary

Summary statistics for mass balance.

Properties

Property	Type	Description
totalInletFlow	number	Total inlet flow (m³/d)
totalEffluentFlow	number	Total final effluent flow (m³/d)
totalSludgeProduction	number	Total sludge production (kg DS/d)
overallBODRemoval	number	BOD removal efficiency (%)
overallTSSRemoval	number	TSS removal efficiency (%)
overallAmmNRemoval	number	Ammonia removal efficiency (%)
overallPRemoval	number	P removal efficiency (%)
numberOfProcessUnits	number	Number of process units
numberOfStreams	number	Number of streams

Example

typescript

// Calculate overall removal efficiency
function calculateOverallRemoval(
  influentLoad: number,
  effluentLoad: number
): number {
  return ((influentLoad - effluentLoad) / influentLoad) * 100;
}

const summary: MassBalanceSummary = {
  totalInletFlow: 60000,
  totalEffluentFlow: 59500,
  totalSludgeProduction: 2400,
  overallBODRemoval: calculateOverallRemoval(12000, 600),  // 95%
  overallTSSRemoval: calculateOverallRemoval(15000, 600),  // 96%
  overallAmmNRemoval: calculateOverallRemoval(2700, 270),  // 90%
  overallPRemoval: calculateOverallRemoval(480, 120),      // 75%
  numberOfProcessUnits: 12,
  numberOfStreams: 24
};

Grid Display

GridRowDefinition

Grid row definition for mass balance table display.

Properties

Property	Type	Description
id	string	Row ID
parameter	string	Parameter name
unit	string	Unit of measurement
category	GridRowCategory	Category for grouping
getValue	(stream: StreamBalance) => number \| null	Function to get value from stream
decimals	number	Number of decimal places

Grid Row Categories

'flow' - Flow conditions
'massLoad' - Mass loading rates
'concentration' - Quality concentrations
'special' - Special parameters (% DS, etc.)

Example

typescript

const customGridRows: GridRowDefinition[] = [
  {
    id: 'dwf',
    parameter: 'Dry weather flow',
    unit: 'm³/day',
    category: 'flow',
    getValue: (s) => s.flows.dwf,
    decimals: 0
  },
  {
    id: 'bodLoad',
    parameter: 'BOD',
    unit: 'kg/day',
    category: 'massLoad',
    getValue: (s) => s.massLoads.bod,
    decimals: 1
  },
  {
    id: 'tssConc',
    parameter: 'Avg conc SS',
    unit: 'mg/L',
    category: 'concentration',
    getValue: (s) => s.concentrations.tss,
    decimals: 0
  },
  {
    id: 'percentDS',
    parameter: '% DS',
    unit: '%',
    category: 'special',
    getValue: (s) => s.concentrations.percentDS ?? null,
    decimals: 2
  }
];

Constants

BALANCE_TOLERANCE_PERCENT

Balance tolerance percentage for mass conservation checks.

Value: 5 (5%)

MIN_FLOW_FOR_CONCENTRATION

Minimum flow for concentration calculation to avoid division by zero.

Value: 0.001 (m³/d)

Usage Examples

Creating a Mass Balance

typescript

// Build streams
const streams: StreamBalance[] = [
  {
    streamId: 'F1',
    streamNumber: 1,
    description: 'Raw Influent',
    sourceUnit: 'Inlet',
    targetUnit: 'PST',
    streamType: 'mainProcess',
    flows: { dwf: 50000, average: 60000, fft: 90000 },
    massLoads: { tss: 15000, bod: 12000, ammN: 2700, tp: 480 },
    concentrations: { tss: 250, bod: 200, ammN: 45, tp: 8 },
    isSludgeStream: false
  }
];

// Perform balance checks
const checks: BalanceCheck[] = streams.map(stream => ({
  parameter: 'Flow',
  location: stream.targetUnit,
  totalIn: stream.flows.average,
  totalOut: stream.flows.average,
  difference: 0,
  percentDifference: 0,
  balanced: true
}));

// Create mass balance
const massBalance: ProcessCalcMassBalance = {
  scenarioName: 'Current Conditions',
  scenarioType: 'Current',
  generatedAt: new Date(),
  streams,
  processUnits: [],
  balanceChecks: checks,
  notes: [],
  balanceStatus: 'Balanced',
  summary: {
    totalInletFlow: 60000,
    totalEffluentFlow: 59500,
    totalSludgeProduction: 2400,
    overallBODRemoval: 95,
    overallTSSRemoval: 96,
    overallAmmNRemoval: 90,
    overallPRemoval: 75,
    numberOfProcessUnits: 8,
    numberOfStreams: 20
  }
};

StreamData - Simulation engine stream interface
ProcessUnitBalance - Process unit configuration

Clarification

Disinfection

Filtration

Membranes

Mass Balance API Reference ​

Overview ​

Core Types ​

MassBalanceScenarioType ​

Values ​

FlowConditionType ​

Values ​

StreamType ​

Values ​

Stream Data Structures ​

StreamFlowConditions ​

Properties ​

Example ​

StreamMassLoads ​

Properties ​

Example ​

StreamConcentrations ​

Properties ​

Example ​

StreamBalance ​

Properties ​

Example ​

Process Unit Data Structures ​

ProcessUnitBalance ​

Properties ​

Duty Configuration ​

Removal Efficiencies ​

Example ​

Balance Verification ​

BalanceCheck ​

Properties ​

Balance Parameters ​

Example ​

Complete Mass Balance ​

ProcessCalcMassBalance ​

Properties ​

Example ​

MassBalanceSummary ​

Properties ​

Example ​

Grid Display ​

GridRowDefinition ​

Properties ​

Grid Row Categories ​

Example ​

Constants ​

BALANCE_TOLERANCE_PERCENT ​

MIN_FLOW_FOR_CONCENTRATION ​

Usage Examples ​

Creating a Mass Balance ​

Related Types ​

Mass Balance API Reference

Overview

Core Types

MassBalanceScenarioType

Values

FlowConditionType

Values

StreamType

Values

Stream Data Structures

StreamFlowConditions

Properties

Example

StreamMassLoads

Properties

Example

StreamConcentrations

Properties

Example

StreamBalance

Properties

Example

Process Unit Data Structures

ProcessUnitBalance

Properties

Duty Configuration

Removal Efficiencies

Example

Balance Verification

BalanceCheck

Properties

Balance Parameters

Example

Complete Mass Balance

ProcessCalcMassBalance

Properties

Example

MassBalanceSummary

Properties

Example

Grid Display

GridRowDefinition

Properties

Grid Row Categories

Example

Constants

BALANCE_TOLERANCE_PERCENT

MIN_FLOW_FOR_CONCENTRATION

Usage Examples

Creating a Mass Balance

Related Types