Project 35: PyMath Core Engine

A self-contained deep-dive from the canonical Math from Foundations to Machine Learning curriculum.

  • Difficulty: Expert
  • Time: 4-6 weeks
  • Language: Python with NumPy, Matplotlib, and optional SymPy only as a verifier
  • Prerequisites: Projects 3, 5, 11, 20, 26-29, and 34
  • Merged from: HS PyMath Engine; HS High School Math Core Engine

What You Will Build

Build one modular command-line and notebook system integrating the strongest earlier high-school mathematics tools behind stable contracts. Its expression pipeline parses, normalizes, evaluates, and verifies inputs. Modules solve equations and inequalities, analyze functions, classify linear systems, inspect sequences and conics, compute numerical derivatives and integrals, fit regression models, and run seeded probability/modeling scenarios. A shared report layer renders formulas, tables, plots, assumptions, warnings, and verification traces. Do not paste earlier scripts into one file: define reusable expression, result, diagnostic, plotting, and scenario interfaces so modules compose. Include a scenario command that takes raw input through parsing, analysis, visualization, and an auditable report in one run.

Real World Outcome

The CLI supports commands such as solve, analyze-function, differentiate, integrate, fit-line, and simulate. A demo notebook processes a problem bundle and emits a single report containing exact/numeric answers, plots, residuals, convergence evidence, assumptions, and deterministic reproduction metadata. Invalid or unsupported problems return typed diagnostics rather than stack traces.

Core Question

How can many mathematical techniques become a coherent, trustworthy software system whose answers carry enough evidence to be checked independently?

Concepts You Must Understand First

  1. Representation contracts: expressions, matrices, intervals, datasets, and scenarios require explicit shapes, domains, and units.
  2. Separation of concerns: parsing, mathematics, verification, presentation, and persistence should not depend circularly on one another.
  3. Exact versus approximate computation: preserve exact forms where possible and attach tolerances/error evidence to numeric results.
  4. Verification strategies: substitution, residuals, invariants, convergence studies, and seeded replication validate different modules.
  5. Model assumptions: probabilistic and regression outputs need units, data provenance, and limitation statements. References include Saha, Doing Math with Python; Downey, Think Stats; and Orland, Math for Programmers.

Build Milestones

  1. Design common input, result, diagnostic, and verification records plus a plugin-like module boundary.
  2. Integrate equation/function and matrix/geometry capabilities with regression tests from their original projects.
  3. Integrate calculus operations with shared domain checks, convergence controls, and plotting.
  4. Add seeded probability, regression, and scenario modules with consistent report output.
  5. Build an end-to-end notebook/CLI demo, documentation, and a cross-module test suite.

Hints in Layers

  1. Choose one vertical slice—parse a function, evaluate it, plot it, verify a claim, export a report—before adding commands.
  2. Return structured results; presentation code should never scrape printed strings.
  3. Let every module register its assumptions and validation evidence so the report layer remains generic.

Common Pitfalls and Debugging

  • Symptom: adding one command breaks unrelated modules. Cause: shared mutable state or tight coupling. Fix: isolate pure domain services behind typed interfaces.
  • Symptom: numeric answers disagree without explanation. Cause: modules use inconsistent tolerances/domains. Fix: centralize numeric policy while allowing explicit overrides.
  • Symptom: the engine is only a menu of scripts. Cause: no shared contracts or cross-module workflow. Fix: require a scenario to compose at least three capabilities through structured data.

Definition of Done

  • One documented CLI exposes algebra, functions, matrices, calculus, statistics, and modeling modules.
  • Modules share structured results and diagnostics rather than print-only integration.
  • Every operation supplies verification evidence or a stated limitation.
  • Existing project fixtures remain regression tests after integration.
  • A deterministic end-to-end report composes at least three modules.
  • Architecture and extension documentation let another developer add a command safely.

Previous: Project 34 · Complete learning path · Next: Project 36