cognitive-discovery-system

Open-source computational science platform for research, simulation, and discovery.

CDS brings together quantum computing simulation, statistical analysis, signal processing, optimization, probability, and scientific computing in a single, dependency-light Python package. Every module is pure Python — no NumPy or SciPy required.

The system also includes built-in support for structured hypothesis generation, making it easier to explore ideas and connect them to simulation or analysis tools.

Stable release — see the PyPI version badge above for the latest tag. Contributions welcome!

Documentation | Tutorials | Quick Start

Latest Update: maintenance release fixing the automated publish pipeline (OIDC → scoped PyPI API token; release.yml is now the sole publish authority). No API or behavior changes. The current version is shown in the PyPI badge at the top of this README; see the CI and codecov badges for the live test count and coverage, all in readable pure Python.

Contents

• Why CDS?
• Citing CDS
• Modules
• Quick Start
• Intelligence over Brute Force
• ASCII Visualization & Tools
• Interactive Dashboard
• Scientific Case Studies
• Examples
• Architecture
• Vision
• Recent Improvements
• Contributing
• Automation and Maintenance Workflows
• Security
• License
• Contact

Why CDS?

• Zero heavy dependencies — pure Python implementations you can read and learn from
• Quantum simulation — single & multi-qubit circuits with entanglement
• Built for discovery — hypothesis generation with structured outputs (assumptions, predictions, confidence) plus a Protocol for custom implementations
• Broad scope — the module catalog below covers math, physics, stats, ML, signals, optimization, graph theory, ODEs, numerical integration, Monte Carlo, knowledge organization, and educational NLP (BPE + embeddings)
• Thoroughly tested — the full suite runs on every push; see the CI badge for the live test count and the codecov badge for 100% code coverage (statement + branch)
• Practical automation — workflows for PR checklists, dependency updates, and releases to keep maintenance manageable
• CLI included — interactive tools, demos, and ASCII visualization from your terminal

CDS vs other libraries

When to use CDS: teaching, prototyping, scientific exploration, edge deployments, custom algorithm development. When to reach for NumPy/SciPy/PennyLane: production HPC, GPU-accelerated quantum, distributed compute.

Citing CDS

If CDS is useful in your research or publications, please cite it using the information in CITATION.cff at the repository root. This helps give proper credit and track adoption in scientific work.

Modules

Quick Start

git clone https://github.com/Furox88/cognitive-discovery-system.git
cd cognitive-discovery-system
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Run tests
pytest

# CLI usage
cds --help
cds constants
cds calc ke
cds modules
cds hypothesis "What causes the Hubble tension?"

Intelligence over Brute Force

CDS is built on the principle that algorithmic improvements matter more than raw loop speed. Pure Python cannot match C-extensions for tight loops, so CDS closes the gap where it can through better algorithms:

• Quantum Simulation: Instead of multiplying state matrices for every shot, CDS uses O(1) probabilistic sampling with explicit state collapse, which is significantly faster than the naive shot-by-shot approach.
• Linear Algebra: Uses O(N³) Partial Pivoting LU Decomposition in place of the naive O(N!) determinant expansion.
• Signal Processing: Zero-padded O(N log N) FFT and FFT-based convolution via the Convolution Theorem.
• Neural Networks: Adam optimizers with momentum state persistence.

See the full Intelligence & Performance Benchmark Report for detailed figures.

ASCII Visualization & Tools

You don't need heavy plotting libraries to inspect your data. CDS includes a built-in terminal visualization engine:

# Plot a sine wave or data series directly in your terminal
cds plot "1, 5, 3, 8, 4, 9" --title "My Data"

Outputs scale-aware ASCII line plots and bar charts.

Interactive Dashboard

CDS includes an Interactive Web Dashboard for scientific exploration. Launch it from your terminal:

pip install "cognitive-discovery-system[dashboard]"
cds dashboard

The dashboard includes a Hypothesis Engine, Quantum Circuit Simulator, Neural Network training visualizer, and Statistical testing lab.

Scientific Case Studies

Explore how CDS is used to solve real-world research problems:

1. Hubble Tension Analysis: Generating and testing hypotheses for the expansion rate of the universe.
2. Quantum-ML Integration: Using quantum circuit measurements as features for classical Neural Network training.

Examples

See the examples/ directory for runnable demos and docs/research-workflows.md for guidance on embedding CDS in research pipelines.

Hypothesis Generation (cognitive discovery)

# Basic demo
python examples/hypothesis_demo.py

# With stats / experiment sketch example
python examples/hypothesis_with_stats_demo.py

# Custom generator implementation (using the HypothesisGenerator Protocol)
python examples/hypothesis_custom_generator.py

# Or via CLI
cds hypothesis "What causes the Hubble tension?"

Quantum Circuit (single qubit)

from cds.quantum import QuantumCircuit, hadamard, pauli_x, simulate

circuit = QuantumCircuit().add(hadamard()).add(pauli_x())
result = circuit.run()
print(result.probabilities())

counts = simulate(circuit, shots=1000)
print(counts)  # {0: ~500, 1: ~500}

Multi-Qubit & Entanglement

from cds.quantum import (
    QuantumRegister, h_gate, cnot, bell_state,
    ghz_state, is_entangled,
)

# Bell state (|00⟩ + |11⟩) / √2
reg = bell_state(0)
print(is_entangled(reg))  # True
print(reg.measure_shots(shots=1000))  # {'00': ~500, '11': ~500}

# 4-qubit GHZ state
ghz = ghz_state(4)
counts = ghz.measure_shots(shots=1000)
print(counts)  # {'0000': ~500, '1111': ~500}

Optimization

from cds.optimization import gradient_descent, newton_method

# Find minimum of (x-3)²
result = gradient_descent(lambda x: (x - 3) ** 2, x0=10.0, lr=0.1)
print(f"x = {result.x:.6f}")  # ~3.0

# Find √2 using Newton's method
result = newton_method(lambda x: x ** 2 - 2, x0=1.5)
print(f"√2 = {result.x:.10f}")  # 1.4142135624

Signal Processing

from cds.signals import dft, fft_radix2, convolve, low_pass_filter

# FFT of a signal
signal = [complex(i) for i in range(8)]
spectrum = fft_radix2(signal)

# Convolution
result = convolve([1.0, 2.0, 3.0], [0.5, 0.5])
print(result)  # [0.5, 1.5, 2.5, 1.5]

Probability Distributions

from cds.probability import gaussian_pdf, binomial_pmf, poisson_pmf

# Gaussian PDF at x=0
print(gaussian_pdf(0.0, mu=0, sigma=1))  # 0.3989...

# Binomial: P(3 heads in 5 fair flips)
print(binomial_pmf(3, 5, 0.5))  # 0.3125

# Poisson: P(k=2, λ=3)
print(poisson_pmf(2, 3.0))  # 0.2240...

Statistics

from cds.stats import mean, stdev, correlation, linear_regression

data = [12.5, 14.3, 11.8, 15.1, 13.7]
print(f"mean={mean(data):.2f}, std={stdev(data):.2f}")

x = [1, 2, 3, 4, 5]
y = [2.1, 3.9, 6.2, 7.8, 10.1]
reg = linear_regression(x, y)
print(f"y = {reg.slope:.2f}x + {reg.intercept:.2f}, R²={reg.r_squared:.3f}")

Machine Learning

from cds.ml import Layer, MLP

# Simple XOR-like Neural Network
net = MLP([
    Layer(2, 4, activation="relu"),
    Layer(4, 1, activation="sigmoid")
])
X, y = [[0, 0], [0, 1], [1, 0], [1, 1]], [[0], [1], [1], [0]]

# Train with built-in Adam optimizer
history = net.train(X, y, epochs=50, lr=0.1)
print(f"Final loss: {history['final_loss']:.4f}")

Data Analysis & Visualization

from cds.data_analysis import DataSet, plot_bar

# Mini-Pandas DataSet for filtering and grouping
data = [{"name": "A", "score": 88}, {"name": "B", "score": 92}]
ds = DataSet(data)
filtered = ds.filter(lambda row: row["score"] > 90)
print(filtered.column("name"))  # ['B']

# Terminal Visualization
scores = {row["name"]: row["score"] for row in ds.to_list()}
print(plot_bar(scores, title="Scores"))

Scientific Computing

from cds.scientific import kinetic_energy, escape_velocity, get_constant

print(get_constant("c"))          # speed of light
print(kinetic_energy(10, 5))      # 125.0 J
print(escape_velocity(5.972e24, 6.371e6))  # ~11186 m/s

Graph Theory

from cds.graph import Graph, dijkstra, kruskal_mst, bfs

g = Graph(n_vertices=4, directed=False)
g.add_edge(0, 1, 1.0)
g.add_edge(1, 2, 2.0)
g.add_edge(2, 3, 3.0)
g.add_edge(0, 3, 10.0)

dist, prev = dijkstra(g, 0)
print(dist)  # {0: 0.0, 1: 1.0, 2: 3.0, 3: 6.0}

edges, total = kruskal_mst(g)
print(f"MST weight: {total}")  # 6.0

Mathematical Modeling

from cds.modeling import Variable, Sin, Exp, solve_equation

x = Variable("x")
expr = Sin(x) * Exp(x)        # sin(x) * e^x

# Symbolic derivative (chain + product rules)
print(expr.diff("x").to_str())

# Solve x^2 - 2 = 0  =>  x = sqrt(2)
root = solve_equation(Variable("x") ** 2 - 2, variable="x", x0=1.0)
print(root.x)                 # ~1.4142
print(root.converged)         # True

Knowledge Organization

from cds.knowledge import KnowledgeGraph, Notebook, search

kg = KnowledgeGraph(name="Cosmology")
kg.link_concepts("Dark Energy", "Hubble Constant", kind="affects")
kg.link_concepts("Hubble Constant", "CMB", kind="constrains")

# Shortest path across the (undirected) graph
print(kg.find_path("Dark Energy", "CMB"))
# ['Dark Energy', 'Hubble Constant', 'CMB']

nb = Notebook(name="Lab Book")
nb.add_note("n1", "Hubble Tension", "Local vs CMB H0 disagree.",
            tags=["experiment"], linked_concepts=["Hubble Constant"])

# Ranked retrieval across both concepts and notes
for hit in search(kg, nb, query="hubble"):
    print(hit.concept_name or hit.note_id, hit.score)

Monte Carlo Simulation

import math
from cds.montecarlo import estimate_pi, mc_integrate

if __name__ == "__main__":
    # Unit-circle method
    result = estimate_pi(n_samples=100_000, seed=42)
    print(f"PI approximation: {result.estimate:.4f}")

    # Integration
    area = mc_integrate(math.sin, 0, math.pi, n_samples=100_000)
    print(f"Integral of sin(x): {area.estimate:.4f}")

Differential Equations

from cds.diffeq import rk4, solve_system
import math

# dy/dt = -y, y(0)=1  =>  y(t) = e^(-t)
sol = rk4(lambda t, y: -y, t0=0, y0=1.0, t_end=2.0)
print(f"y(2) = {sol.y[-1]:.6f}")  # ~0.135335 (e^-2)

# Harmonic oscillator: x'' = -x
def harmonic(t, y):
    return [y[1], -y[0]]
t_vals, y_vals = solve_system(harmonic, 0, [1.0, 0.0], math.pi)
print(f"x(π) = {y_vals[-1][0]:.4f}")  # ~-1.0

Numerical Integration

import math
from cds.numerical_integration import simpson, gaussian_quadrature, romberg

# ∫_0^π sin(x) dx = 2
print(simpson(math.sin, 0, math.pi, n=100))  # ~2.0, O(h⁴)

# Gauss-Legendre: exact for polynomials up to degree 2n-1
print(gaussian_quadrature(lambda x: x**7, 0, 1, n=4))  # 0.125 (exact)

# Romberg reaches full machine precision on smooth integrands
result = romberg(math.exp, 0, 1, tol=1e-12)
print(f"∫e^x = {result.value:.10f}")  # ~1.7182818285

Architecture

src/cds/
├── quantum/        # Quantum circuit simulation (single & multi-qubit)
├── optimization/   # Gradient descent, Newton, Adam, line search
├── ml/             # Neural Networks (MLP, Layers, Adam training)
├── signals/        # DFT, FFT, convolution, filtering
├── probability/    # Probability distributions & sampling
├── stats/          # Statistical analysis & regression
├── math_utils/     # Calculus, linear algebra, eigenvalues, Gram-Schmidt
├── data_analysis/  # Mini-Pandas DataSet, CSV loading, ASCII viz
├── scientific/     # Physical constants & formulas
├── graph/          # Graph algorithms (Dijkstra, BFS, DFS, Kruskal MST)
├── modeling/       # Symbolic math (expressions, MathModel, solvers)
├── knowledge/      # Knowledge graph, concepts, notes, structured retrieval
├── montecarlo/     # Monte Carlo methods (π, integration, random walks)
├── diffeq/         # ODE solvers (Euler, RK4, midpoint)
├── numerical_integration/  # Deterministic quadrature (trapezoid, Simpson, Romberg, Gauss-Legendre)
├── nlp/            # Educational NLP (BPE, embeddings, attention, autograd, MiniGPT)
├── hypothesis/     # Hypothesis generation
├── core/           # Shared models, config
└── cli.py          # Command-line interface

examples/           # Runnable demo scripts
tests/              # full test suite (see CI badge for the live count)
docs/               # MkDocs documentation, tutorials, benchmarks
.github/workflows/  # Automation for PRs (labels + checklist), releases, and dependency updates

Vision

The long-term goal of CDS is to provide a lightweight, dependency-free platform for scientific exploration and discovery.

We aim to combine solid numerical foundations (quantum simulation, FFT, linear algebra, statistics, differential equations, etc.) with higher-level tools for hypothesis generation and research workflows.

A distinctive part is the cds.hypothesis module, which generates structured, falsifiable hypotheses with explicit assumptions and predictions. The cds hypothesis CLI command and examples/hypothesis_demo.py make this side immediately usable. Recent work has focused on making the CLI and docs more practical for day-to-day use while keeping everything readable pure Python.

The project is still early but is being actively developed with a focus on code quality, test coverage, documentation, and usability for researchers and students.

Run cds modules after installation to explore the current modules.

Recent improvements

Recent releases (v1.1.x) focused on reliability, type-safety, and a hardened release pipeline rather than new modules:

• 100% blended coverage gate (v1.1.5) — CI now fails unless both statement and branch coverage reach 100%; property-based invariant tests and shared fixtures were added.
• Python 3.13 support (v1.1.5) — the full suite is green on 3.10–3.13.
• Automated release pipeline (v1.1.6) — pushing a v* tag now builds, publishes to PyPI via a scoped API token, cuts a GitHub Release, and attests build provenance (sigstore). release.yml is the sole publish authority.
• PEP 639 SPDX license metadata (v1.1.7) — the license declaration is now a valid SPDX expression recognized on both PyPI and GitHub.
• ODE backward integration bug fix (v1.1.8) — the fixed-step and adaptive ODE solvers (euler/rk4/midpoint/rk45/solve_system) silently returned only the initial value when t_end < t0; integration direction is now derived from sign(t_end - t0) so backward integration actually works. Forward behavior is unchanged. Includes 7 new regression tests and corrected deep-verification scripts.
• Tutorials & architecture docs (v1.1.5) — guided walkthroughs for optimization, signals, ML, statistics, and an architecture section in CONTRIBUTING.md.

See CHANGELOG.md for the full release history.

Contributing

See CONTRIBUTING.md for setup and guidelines.

Looking for:

• Researchers with domain expertise
• People interested in pure-Python scientific computing
• Contributors for new modules (ML basics, PDE solvers, etc.)
• People who want to help make scientific tools easier to maintain and use

Automation and Maintenance Workflows

A few GitHub Actions handle repetitive aspects of keeping the project running:

• Dependabot for regular updates to dependencies and GitHub Actions
• Automatic labeling and review checklists for pull requests
• An automated release pipeline: pushing a version tag builds, publishes to PyPI via a scoped API token, cuts a GitHub Release with artifacts, and attests build provenance (sigstore)

These help ensure that time spent on the project goes more toward developing new modules, improving hypothesis tools, and supporting research use cases rather than manual upkeep.

See .github/workflows/ for the current setup.

License

MIT — see LICENSE.

Contact

• Maintainer: @Furox88
• Issues & Discussions: GitHub

Security

Found a vulnerability? Please do not open a public issue. Report it privately:

• GitHub private advisory: Report a vulnerability
• Or email the maintainer directly.

Acknowledgement target: 48 hours · Fix SLA: 7 days. Full threat model, supported versions, and out-of-scope items are in SECURITY.md.

Why all the automation? CDS is maintained solo. The workflows above (PR labeling, checklists, releases, dependency rotation) exist so routine housekeeping takes minutes, leaving the bulk of maintainer time for the actual science — improving the hypothesis tools, adding modules, and writing better examples.