{"id":30049962,"url":"https://github.com/pabloagn/flux","last_synced_at":"2026-05-17T11:33:01.384Z","repository":{"id":308569054,"uuid":"839105219","full_name":"pabloagn/flux","owner":"pabloagn","description":"An open source, declarative digital twin engine for electrochemical processes, written in Rust.","archived":false,"fork":false,"pushed_at":"2025-10-07T15:31:34.000Z","size":144277,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-07T17:40:02.947Z","etag":null,"topics":["chemical-engineering","declarative-programming","digital-twin","digital-twins","nix","nix-flake","process-engineering","rust","thermodynamics"],"latest_commit_sha":null,"homepage":"https://pabloagn.com/projects/flux","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pabloagn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-08-07T01:34:44.000Z","updated_at":"2025-10-07T15:31:39.000Z","dependencies_parsed_at":"2025-08-06T17:49:00.181Z","dependency_job_id":"39227af3-0eb7-499a-b8bd-2289f676c32b","html_url":"https://github.com/pabloagn/flux","commit_stats":null,"previous_names":["pabloagn/flux"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/pabloagn/flux","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pabloagn%2Fflux","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pabloagn%2Fflux/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pabloagn%2Fflux/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pabloagn%2Fflux/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pabloagn","download_url":"https://codeload.github.com/pabloagn/flux/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pabloagn%2Fflux/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33136741,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-17T09:28:26.183Z","status":"ssl_error","status_checked_at":"2026-05-17T09:27:52.702Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chemical-engineering","declarative-programming","digital-twin","digital-twins","nix","nix-flake","process-engineering","rust","thermodynamics"],"created_at":"2025-08-07T12:41:52.830Z","updated_at":"2026-05-17T11:33:01.377Z","avatar_url":"https://github.com/pabloagn.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cbr/\u003e\n\u003cp align=\"center\"\u003e\u003cimg src=\"assets/FLUX.png\" width=500px\u003e\u003c/p\u003e\n\u003cbr/\u003e\n\u003cp align=\"center\"\u003e\u003cem\u003eIndustrial-Grade Chlor-Alkali Digital Twin Platform\u003c/em\u003e\u003c/p\u003e\n\n\u003cbr/\u003e\n\u003cdiv align=\"center\"\u003e───────  ⏣  ───────\u003c/div\u003e\n\u003cbr/\u003e\n\u003cbr/\u003e\n\n\u003cdiv align =\"center\"\u003e\n\n[![Last Commit](https://img.shields.io/github/last-commit/pabloagn/flux?style=for-the-badge\u0026logo=git\u0026logoColor=white\u0026color=7AA89F\u0026labelColor=000000\u0026label=LAST%20COMMIT)](https://github.com/pabloagn/flux/commits/main) [![License](https://img.shields.io/github/license/pabloagn/flux?style=for-the-badge\u0026color=7AA89F\u0026labelColor=000000)](https://github.com/pabloagn/flux/blob/main/LICENSE)\n\n\u003c/div\u003e\n\n## Executive Summary\n\nFLUX is a production-ready digital twin platform for chlor-alkali electrolysis plants, processing 1M+ events/second from 180+ electrolytic cells. The system provides real-time plant control, predictive maintenance, and operational optimization while maintaining SIL-3 safety standards.\n\n## Industry Context\n\nThe global chlor-alkali market represents an $80+ billion industry, with membrane cell technology dominating 65% of worldwide production capacity. Energy costs constitute 40-50% of total production costs, while membrane replacement represents 30-40% of operational expenses. Current industrial control systems lack the real-time optimization and predictive capabilities needed to address these economic pressures.\n\n## Business Problems Addressed\n\n### Membrane Degradation Management\n\n**Challenge**: Membrane lifetime varies from 2-7 years with replacement costs of $500-1000/m². Current efficiency drops from 96% to 85% over membrane lifetime, with voltage increases of 0.2-0.5V. Unplanned membrane failures cause 5-10 days of downtime, costing millions in lost production.\n\n**FLUX Solution**: Real-time membrane health monitoring using Butler-Volmer kinetics and ML-based degradation models. Predictive maintenance scheduling reduces unplanned downtime by 80% and extends membrane life by 15-20% through optimized operating conditions.\n\n### Brine Quality Impact\n\n**Challenge**: Impurities (Ca²⁺, Mg²⁺, SO₄²⁻) cause membrane fouling, requiring \u003c20 ppb for optimal operation. Poor brine quality reduces current efficiency by 2-5%, directly impacting profitability.\n\n**FLUX Solution**: Temporal correlation between upstream brine quality and downstream cell performance using GlassFlow's streaming joins. Accounts for 2-4 hour residence times, enabling proactive process adjustments before efficiency degradation occurs.\n\n### Current Distribution Optimization\n\n**Challenge**: 5-10% variation in individual cell voltages within electrolyzers causes hotspots that reduce membrane lifetime by up to 50%. Manual redistribution is typically done quarterly, missing optimization opportunities.\n\n**FLUX Solution**: Continuous current distribution monitoring across all 180 cells with automatic rebalancing recommendations. Real-time optimization algorithms minimize cell-to-cell variations to \u003c2%, significantly extending equipment life.\n\n### Energy Cost Management\n\n**Challenge**: Electricity represents 40-50% of production costs with volatile spot pricing. Load flexibility is limited by product demand, and startup/shutdown cycles damage membranes, constraining optimization options.\n\n**FLUX Solution**: Dynamic load optimization integrating spot price forecasts, demand predictions, and equipment constraints. Operates within 85-95% turndown capability while maintaining product quality, achieving 5-10% energy cost reduction.\n\n## Plant Configuration\n\n### Physical Layout\n\nThe reference implementation models a world-scale chlor-alkali facility:\n\n- **Capacity**: 1000 MT/day Cl₂ (365,000 MT/year)\n- **Configuration**: 3 electrolyzer units × 100 MW each\n- **Cell Count**: 180 cells (3 units × 3 stacks × 20 cells)\n- **Technology**: Modern membrane cells (DuPont N2030 or equivalent)\n- **Integration**: Complete brine treatment and product handling systems\n\n### Operating Parameters\n\n| Parameter | Value | Impact on Digital Twin |\n|-----------|-------|------------------------|\n| Current Density | 4-6 kA/m² | Determines production rate and efficiency |\n| Cell Temperature | 85-90°C | Critical for membrane life and efficiency |\n| Pressure Differential | 100-300 mbar | Safety-critical parameter for membrane integrity |\n| Brine Concentration | 300 g/L inlet, 200 g/L outlet | Mass balance and efficiency calculations |\n| NaOH Product | 32% concentration | Product quality control |\n\n## Value Proposition\n\n### Quantifiable Benefits\n\n- **Efficiency Improvement**: 2-3% increase in current efficiency = $8-12M annual savings\n- **Membrane Life Extension**: 15-20% longer life = $3-5M reduced replacement costs\n- **Energy Optimization**: 5-10% reduction = $10-20M annual savings\n- **Downtime Reduction**: 80% fewer unplanned shutdowns = $15-25M recovered production\n- **Total Annual Value**: $36-62M for a 1000 MT/day facility\n\n### Competitive Advantages\n\n- **Latency**: \u003c10ms control loop vs. 100-500ms in traditional DCS\n- **Scale**: Handles 1M+ events/sec vs. 10-100K in conventional systems\n- **Intelligence**: Embedded ML models vs. rule-based control\n- **Safety**: SIL-3 certified with cryptographic command verification\n- **Flexibility**: Cloud-native architecture vs. monolithic legacy systems\n\n## System Architecture\n\n### Data Pipeline Architecture\n\nThe platform implements a lambda architecture with specialized pipelines optimized for different operational requirements:\n\n#### High-Speed Control Pipeline (Latency: \u003c10ms)\n```\nSensors → TSN Network → OPC UA → Kafka → QuestDB → Control TUI\n                                    ↓\n                             ScyllaDB (State Store)\n```\n\n#### Analytics Pipeline (Latency: 1-5s)\n```\nSensors → Kafka → GlassFlow → ClickHouse → Analytics Dashboard\n                     ↓\n               ML Microservices → Predictions\n```\n\n#### Audit \u0026 Compliance Pipeline\n```\nAll Events → Apache Pulsar (Cryptographic Signing) → TimescaleDB\n                    ↓\n               Immutable Audit Trail\n```\n\n### Core Components\n\n#### Real-Time Data Layer\n- **QuestDB**: Ingests 1M+ events/sec with nanosecond precision timestamps\n- **ScyllaDB**: Maintains complete plant state with 10μs p99 latency\n- **Redis**: Hot cache for control loops requiring \u003c1ms access\n\n#### Historical \u0026 Analytics Layer\n- **ClickHouse**: Columnar storage for multi-year historical data\n- **GlassFlow**: Stream processing for temporal joins and deduplication\n- **TimescaleDB**: Regulatory compliance and audit trail\n\n#### Control Systems\n- **OPC UA Server**: Industrial protocol interface with TSN support\n- **Safety Interlock System**: SIL-3 rated safety logic with 10ms override capability\n- **Redundancy**: 3-node etcd cluster for leader election, automatic failover \u003c2s\n\n#### Machine Learning Platform\n- **TorchServe**: Membrane degradation and efficiency prediction models\n- **NVIDIA Triton**: GPU-accelerated electrochemical calculations\n- **MLflow**: Model versioning and experiment tracking\n- **Feast**: Real-time feature store for ML pipelines\n\n### Safety Architecture\n\n#### Write-Back Security\n- Ed25519 cryptographic signatures on all control commands\n- Challenge-response authentication for command authorization\n- Dual-path verification through separate validation service\n- Hardware watchdog timers on control-enabled instances\n\n#### Failsafe Mechanisms\n- Dead-man's switch: Automatic control disengagement on TUI disconnect\n- SIS override: Hardware safety system can veto any software command\n- Command expiry: Control commands auto-expire after 100ms\n- State rollback: Automatic reversion to safe state on anomaly detection\n\n### Data Flow Specifications\n\n#### Message Distribution (1M+ events/sec)\n- **High-frequency (600K/sec)**: Voltage, current @ 100Hz per cell\n- **Medium-frequency (300K/sec)**: Pressure, electrolyte levels @ 10Hz\n- **Low-frequency (100K/sec)**: Temperature, chemical composition @ 1Hz\n- **Derived calculations**: KPIs, efficiency metrics, predictions\n\n#### Time Synchronization\n- PTP (IEEE 1588) grandmaster with GPS reference\n- Sub-microsecond synchronization across all nodes\n- Automatic clock drift compensation\n- NTP fallback for non-critical systems\n\n## Electrochemical Process Model\n\n### Fundamental Reactions\n\nThe chlor-alkali process operates via the following half-reactions:\n\n**Anode (Chlorine Evolution)**:\n$$2Cl^- → Cl_2 + 2e^- \\quad E^0 = 1.36V$$\n\n**Cathode (Hydrogen Evolution)**:\n$$2H_2O + 2e^- → H_2 + 2OH^- \\quad E^0 = -0.83V$$\n\n**Overall Cell Reaction**:\n$$2NaCl + 2H_2O → Cl_2 + H_2 + 2NaOH \\quad E^0_{cell} = 2.19V$$\n\n### Production Calculations\n\nBased on Faraday's laws of electrolysis:\n\n$$m = \\frac{M \\cdot I \\cdot t \\cdot \\eta}{n \\cdot F}$$\n\nWhere:\n- m = mass of product (kg)\n- M = molar mass (kg/mol): Cl₂ = 0.0709, H₂ = 0.00202, NaOH = 0.040\n- I = current (A)\n- t = time (s)\n- η = current efficiency (0.94-0.96)\n- n = electrons transferred (2 for Cl₂ and H₂)\n- F = Faraday constant (96,485 C/mol)\n\n### Cell Voltage Model\n\n$$V_{cell} = E^0 + \\eta_{act} + \\eta_{ohm} + \\eta_{conc}$$\n\nWhere:\n- E^0 = 2.19V (thermodynamic potential at 85°C)\n- η_act = Activation overpotential (Butler-Volmer kinetics)\n- η_ohm = Ohmic losses (membrane + electrolyte resistance)\n- η_conc = Concentration overpotential\n\n$$\\eta_{act} = \\frac{RT}{αnF} \\ln\\left(\\frac{i}{i_0}\\right)$$\n\n### Energy Efficiency Metrics\n\n**Specific Energy Consumption**:\n$$SEC = \\frac{\\int V(t) \\cdot I(t) \\, dt}{m_{Cl_2}} \\quad \\text{[kWh/MT]}$$\n\nTarget: \u003c2,450 kWh/MT Cl₂\n\n**Current Efficiency**:\n$$CE = \\frac{m_{actual}}{m_{theoretical}} \\times 100\\%$$\n\nTarget: \u003e94%\n\n## Performance Specifications\n\n### System Requirements\n- **Throughput**: 1M+ events/second sustained\n- **Control Latency**: \u003c10ms sensor-to-actuator\n- **Analytics Latency**: \u003c5s for complex queries\n- **Data Retention**: 24hr hot (QuestDB), 10yr cold (ClickHouse)\n- **Availability**: 99.99% uptime (52 minutes downtime/year)\n\n### Hardware Requirements\n\n#### Minimum Production Deployment\n- **Control Nodes**: 3x servers with TSN NICs, PTP support\n- **Database Cluster**: 5x nodes (QuestDB: 2, ClickHouse: 3)\n- **ML Compute**: 2x GPU nodes (NVIDIA A100 or equivalent)\n- **State Store**: 3x NVMe nodes for ScyllaDB\n- **Memory**: 512GB RAM total across cluster\n- **Storage**: 100TB SSD for hot data, 1PB HDD for cold\n\n### Network Architecture\n- **Control Network**: TSN-enabled switches, redundant paths\n- **Data Network**: 100Gbps backbone, RDMA support\n- **Synchronization**: Dedicated PTP VLAN\n- **Security**: Air-gapped control network, DMZ for external access\n\n## Deployment\n\n### Prerequisites\n```bash\n# System requirements\n- Kubernetes 1.28+ with GPU operator\n- Nix with flakes enabled\n- Docker 24.0+\n- etcd 3.5+\n- PTP-enabled network hardware\n```\n\n### Quick Start\n```bash\n# Initialize Nix environment\nnix develop\n\n# Deploy infrastructure\nflux-setup                          # Create directory structure\nflux-deploy-core                    # Deploy Kafka, QuestDB, ClickHouse\nflux-deploy-ml                       # Deploy ML platform\nflux-deploy-control                  # Deploy OPC UA, SIS interface\n\n# Start simulation\nnix develop .#simulator\npython -m flux.simulation --mode=closed-loop --cells=180\n\n# Launch control TUI (requires authorization)\nexport FLUX_CONTROL_KEY=/path/to/key.pem\nnix develop .#tui\ncargo run --release --features=control\n\n# Verify pipelines\nflux-health-check --all\n```\n\n### Production Deployment\n```bash\n# Deploy with Terraform\ncd infra/terraform\nterraform init\nterraform plan -var-file=production.tfvars\nterraform apply\n\n# Initialize Kubernetes cluster\nkubectl apply -f infra/kubernetes/namespaces.yaml\nkubectl apply -f infra/kubernetes/crds/\nhelm install flux ./charts/flux -f values.production.yaml\n\n# Configure PTP\nptp4l -i eth0 -m -H -s /etc/ptp4l.conf\nphc2sys -s eth0 -c CLOCK_REALTIME -w -m\n```\n\n## Development Status\n\n### Completed\n- Process simulation engine with electrochemical models\n- Kafka topic architecture for 1M+ events/sec\n- Basic TUI with real-time visualization\n- Nix flake configuration\n\n### In Progress\n- [ ] QuestDB pipeline implementation\n- [ ] ScyllaDB state management\n- [ ] OPC UA server integration\n- [ ] ML microservices deployment\n- [ ] SIS interface implementation\n- [ ] Cryptographic command signing\n\n### Planned\n- [ ] Full closed-loop control implementation\n- [ ] Advanced predictive maintenance models\n- [ ] Energy optimization with grid integration\n- [ ] Multi-plant coordination\n- [ ] Mobile operator interface\n- [ ] AR/VR visualization\n\n## Safety \u0026 Compliance\n\n### Standards Compliance\n- **IEC 61511**: Functional safety for process industries\n- **ISA-84**: Safety instrumented systems\n- **IEC 62443**: Industrial network security\n- **ISO 27001**: Information security management\n- **NIST 800-82**: Industrial control system security\n\n### Safety Integrity Level\n- Control loops: SIL-2 certified\n- Emergency shutdown: SIL-3 certified\n- Alarm management: ISA 18.2 compliant\n\n## Testing\n\n### Simulation Modes\n```bash\n# Open-loop simulation (sensor data only)\npython -m flux.simulation --mode=open-loop\n\n# Closed-loop simulation (with control responses)\npython -m flux.simulation --mode=closed-loop\n\n# Fault injection testing\npython -m flux.simulation --mode=fault --scenario=membrane-rupture\n\n# Load testing (verify 1M events/sec)\nflux-load-test --rate=1000000 --duration=3600\n```\n\n### Verification\n```bash\n# Verify data flow\nflux-trace --event-id=\u003cuuid\u003e --show-path\n\n# Check latencies\nflux-latency-monitor --percentile=99\n\n# Validate calculations\nflux-verify-calculations --reference=aspen-plus\n```\n\n## Contributing\n\nThis is a reference architecture for industrial control systems. Contributions must maintain safety-critical standards and include comprehensive testing.\n\n## License\n\nProprietary - Industrial Reference Architecture\n\n## Support\n\nFor production deployments, [contact me](https://pabloagn.com/contact).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpabloagn%2Fflux","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpabloagn%2Fflux","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpabloagn%2Fflux/lists"}