How fpom/ecco works
Project type and purpose
• ecco is an open-source Python/Cython library (with C++ back-end) for formal modelling and analysis of ecosystems.
File structure
• Top-level:
• bin/ → entry points (ecco.py, desktop launcher)
• ecco/ → Python packages & Cython modules (dr, lrr, mrr, model, graphs, cygraphs, bqcm, ui)
• / → C++ libraries (DDD in include/ddd, ITS in include/its) wrapped by Cython (*.pxd, .pyx)
• doc/ → Jupyter notebooks (documentation & examples)
• setup files (Dockerfile, setup.py, Makefile)
• The architecture is a modular monolith with clear separation between:
• Frontend / UI (CLI, GUI, Jupyter notebooks)
• Core Python/Cython engine (rule parser, state‐space builder, analyzers)
• Native libraries (DDD & ITS C++ code)
• Visualization & persistence (NetworkX, Graphviz, pandas)
Pull insights from the README
• Core modelling language: reaction‐rules (.rr) → Boolean entities + transition rules
• Static analyses independent of state‐space build
• Interactive exploration via Jupyter + BQPlot + ipywidgets
1. CLI/Launcher
• bin/ecco.py → wraps Docker + starts JupyterHub/Notebook
• ecco/__main__.py → python -m ecco entry point
2. Jupyter Server / GUI
• JupyterHub / Jupyter Notebook process
3. Python API / Engine
• ecco/_ui.pyx, ecco/ui.py → interactive widgets & commands
• ecco/dr → drparse.parse_rules(), dr_peg.build_graph()
• ecco/lrr → lts.compute_lts(), match.perform_matching()
• ecco/mrr → lts.compute_mrr_lts(), tables.build_transition_tables()
• ecco/model → model.match.match_model(), record.StateRecord()
• ecco/cygraphs → build_cygraph(), analyze_graph()
• ecco/bqcm → compute_bqm()
• ecco/rr (top‐level state-space): compute_state_space(), static_analysis()
4. Native Libraries
• ITS (include/its): explicit state‐space & model‐checker, wrapped by Cython (its.pxd, itswrap.h)
5. External Services & Tools
• GraphViz (pydot) → graph rendering
• NetworkX → graph algorithms
• pandas, NumPy → data handling
• TatSu → grammar parsing for .rr files
• CLI/Launcher → starts → Jupyter Server / GUI
• User notebooks or CLI commands → invoke → Python API / Engine
• Parser modules (drparse, rrparse) → produce → intermediate rule AST
• State-space builder (compute_state_space) → calls →
• DDD library (symbolic)
• ITS library (explicit)
• Graph modules (cygraphs, tikz, bqcm) → consume → state-space → produce → visualizations
• Persistence (pandas) → stores → analysis results
c. Architectural patterns & design principles:
• Modular layering: clear separation of concerns (UI vs engine vs native libs)
• Cython bridge: Python <→ C++ for performance-critical parts
• Plugin‐style grammar: TatSu for .rr language extensibility
• Notebook-first: entire API exposed via notebooks for exploratory analysis
d. Key technologies/frameworks:
• Python 3, Cython
• C++ (DDD, ITS), wrapped via .pxd/.pyx
• JupyterHub / Jupyter Notebook
• GraphViz, NetworkX, pandas, NumPy, TatSu, BQPlot, ipywidgets
Capturing computation functions
• ecco/dr: parse_rules(), dr_peg(), drparse.parse()
• ecco/lrr: compute_lts(), ltsprop(), match()
• ecco/mrr: compute_mrr_lts(), tables.build(), pattparse()
• ecco/rr: compute_state_space(), static_analysis()
• ecco/cygraphs: build_graph(), to_networkx()
• ecco/bqcm: compute_bqm()
• Cython wrappers: call_ddd(), call_its()