Add mathematical and project documentation

docs/architecture.md

@@ -0,0 +1,170 @@
+
+# System Architecture
+
+## Gradient Explorer
+
+## 1. Overview
+
+Gradient Explorer is an interactive mathematical visualisation application designed to demonstrate the concept of gradients and steepest ascent on a surface.
+
+The application accepts a mathematical function of two variables, evaluates it at a selected point and presents mathematical and graphical results.
+
+The project uses Python, SymPy, NumPy, Matplotlib and Streamlit.
+
+## 2. Technology Stack
+
+| Technology | Purpose |
+|---|---|
+| Python | Core programming language |
+| Streamlit | Interactive user interface |
+| SymPy | Symbolic mathematics and differentiation |
+| NumPy | Numerical operations and coordinate calculations |
+| Matplotlib | Mathematical visualisations |
+| Pytest | Automated testing |
+| Git and GitHub | Version control and collaboration |
+| GitHub Actions | Continuous integration and automated testing |
+
+## 3. Project Structure
+
+```text
+Gradient-Explorer/
+│
+├── .github/
+│   └── workflows/
+│       └── tests.yml
+│
+├── tests/
+│   └── test_equation_parser.py
+│
+├── docs/
+│   ├── math_test_cases.md
+│   └── architecture.md
+│
+├── app.py
+├── equation_parser.py
+├── calculations.py
+├── visualizations.py
+│
+├── README.md
+├── requirements.txt
+└── .gitignore
+```
+
+Note: `calculations.py` and `visualizations.py` represent planned modules and will be added when their implementations are ready.
+
+## 4. Module Responsibilities
+
+### 4.1 app.py — Application Interface
+
+Responsible for:
+- Displaying the Streamlit interface.
+- Accepting mathematical function input.
+- Accepting x and y coordinates.
+- Triggering equation validation and calculations.
+- Displaying mathematical results.
+- Integrating visualisation components.
+
+### 4.2 equation_parser.py — Equation Validation
+
+Responsible for:
+- Validating user-entered mathematical expressions.
+- Restricting input to supported variables, constants and functions.
+- Converting validated expressions into SymPy expressions.
+- Rejecting unsupported or unsafe syntax.
+
+### 4.3 calculations.py — Mathematical Engine
+
+Planned responsibilities:
+- Calculating partial derivatives.
+- Evaluating gradient components.
+- Calculating gradient magnitude.
+- Calculating unit gradient vectors.
+- Handling zero-gradient and undefined cases.
+
+### 4.4 visualizations.py — Graphical Engine
+
+Planned responsibilities:
+- Generating contour plots.
+- Generating heatmaps.
+- Displaying gradient vectors.
+- Representing the function surface and its mathematical behaviour.
+
+### 4.5 tests/ — Automated Testing
+
+Responsible for:
+- Testing equation parsing and validation.
+- Testing mathematical calculations.
+- Checking expected outputs and edge cases.
+- Preventing regressions during development.
+
+### 4.6 docs/ — Project Documentation
+
+Contains:
+- Mathematical test specifications.
+- System architecture.
+- Project report and technical documentation.
+
+## 5. Application Data Flow
+
+The planned application workflow is:
+
+1. User enters a mathematical function.
+2. The application sends the input to the equation parser.
+3. The parser validates the expression and converts it into a SymPy expression.
+4. The mathematical engine calculates partial derivatives and gradient properties.
+5. The visualisation engine generates graphical representations.
+6. Streamlit displays the mathematical and graphical results.
+
+## 6. Conceptual Architecture Diagram
+
+```text
+              USER
+                |
+                v
+        STREAMLIT INTERFACE
+              app.py
+                |
+                v
+        EQUATION VALIDATION
+          equation_parser.py
+                |
+                v
+        MATHEMATICAL ENGINE
+           calculations.py
+                |
+                v
+        VISUALISATION ENGINE
+          visualizations.py
+                |
+                v
+        RESULTS DISPLAY
+         Streamlit Interface
+```
+
+The diagram represents the intended architecture. Some modules are still under development.
+
+## 7. Testing and Continuous Integration
+
+The project uses Pytest for automated testing.
+
+GitHub Actions runs the test suite when changes are pushed to the main branch or submitted through a pull request.
+
+This helps identify errors before changes are merged into the main codebase.
+
+## 8. Development Approach
+
+The project follows a modular development approach.
+
+Each major responsibility is separated into an independent Python module. This improves maintainability, testing and collaboration.
+
+Feature branches and pull requests are used to manage contributions and protect the main branch.
+
+## 9. Future Scope
+
+Potential future improvements include:
+- Interactive three-dimensional surface plots.
+- Directional derivative calculations.
+- User-controlled gradient visualisation.
+- Additional mathematical functions.
+- Improved graph customisation.
+- Expanded automated test coverage.

docs/math_test_cases.md

@@ -0,0 +1,87 @@
+
+# Mathematical Test Cases
+
+## Gradient Explorer
+
+**Purpose:** Define the expected mathematical results used to verify the gradient calculation engine.
+
+These test cases cover partial derivatives, gradient vectors, gradient magnitude, unit gradient vectors and special cases.
+
+---
+
+## 1. Core Mathematical Test Cases
+
+| ID | Function f(x,y) | Evaluation Point (x,y) | Expected Gradient |
+|---|---|---|---|
+| M01 | x² + y² | (1, 2) | (2, 4) |
+| M02 | 3x + 4y | (1, 1) | (3, 4) |
+| M03 | xy | (3, 2) | (2, 3) |
+| M04 | x² - y² | (2, 1) | (4, -2) |
+| M05 | x² + y² | (0, 0) | (0, 0) |
+
+## 2. Expected Partial Derivatives
+
+| ID | ∂f/∂x | ∂f/∂y |
+|---|---|---|
+| M01 | 2x | 2y |
+| M02 | 3 | 4 |
+| M03 | y | x |
+| M04 | 2x | -2y |
+| M05 | 2x | 2y |
+
+## 3. Expected Gradient Magnitudes
+
+The magnitude of a gradient vector is:
+
+|∇f| = √((∂f/∂x)² + (∂f/∂y)²)
+
+| ID | Expected Magnitude |
+|---|---|
+| M01 | √20 ≈ 4.4721 |
+| M02 | 5 |
+| M03 | √13 ≈ 3.6056 |
+| M04 | √20 ≈ 4.4721 |
+| M05 | 0 |
+
+## 4. Expected Unit Gradient Vectors
+
+The unit gradient vector is obtained by dividing the gradient by its magnitude.
+
+| ID | Expected Unit Gradient |
+|---|---|
+| M01 | (1/√5, 2/√5) |
+| M02 | (3/5, 4/5) |
+| M03 | (2/√13, 3/√13) |
+| M04 | (2/√5, -1/√5) |
+| M05 | Undefined (zero gradient) |
+
+A zero gradient has no defined unit gradient vector because division by zero is undefined.
+
+## 5. Edge Cases
+
+| ID | Scenario | Expected Behaviour |
+|---|---|---|
+| E01 | Zero gradient | Magnitude is zero; unit vector is undefined |
+| E02 | Negative coordinates | Derivatives and numerical values are calculated correctly |
+| E03 | Fractional coordinates | Numerical evaluation is supported |
+| E04 | 1/x evaluated at x = 0 | Undefined result is reported |
+| E05 | log(x) evaluated at x = -1 | Non-real result is reported |
+| E06 | Large valid coordinates | Results retain sufficient numerical precision |
+
+## 6. Acceptance Criteria
+
+The gradient calculation engine should satisfy the following:
+
+1. Calculate both partial derivatives correctly.
+2. Evaluate gradient components at the selected coordinates.
+3. Calculate gradient magnitude correctly.
+4. Calculate a unit gradient vector when the gradient is non-zero.
+5. Handle zero gradients without division by zero.
+6. Detect undefined and non-real numerical results.
+7. Preserve sufficient precision in numerical calculations.
+
+## 7. Scope
+
+These test cases define the mathematical expectations for the Gradient Explorer calculation engine.
+
+They serve as a reference for implementation, unit testing and verification.