From c222caafb029e3a52dea38863e5ce2d534a57e38 Mon Sep 17 00:00:00 2001 From: CodingBunny06 <210141639+CodingBunny06@users.noreply.github.com> Date: Sun, 8 Nov 2026 14:04:58 +0530 Subject: [PATCH] Add mathematical and project documentation --- docs/architecture.md | 170 +++++++++++++++++++++++++++++ docs/math_test_cases.md | 87 +++++++++++++++ docs/project_report.md | 233 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 490 insertions(+) create mode 100644 docs/architecture.md create mode 100644 docs/math_test_cases.md create mode 100644 docs/project_report.md diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..b27cc81 --- /dev/null +++ b/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. diff --git a/docs/math_test_cases.md b/docs/math_test_cases.md new file mode 100644 index 0000000..8b64489 --- /dev/null +++ b/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. diff --git a/docs/project_report.md b/docs/project_report.md new file mode 100644 index 0000000..2ff7a56 --- /dev/null +++ b/docs/project_report.md @@ -0,0 +1,233 @@ + +# Gradient Explorer +## Project Report + +**Project Title:** Gradient Explorer – Interactive Mathematical Visualisation of Gradient and Steepest Ascent + +**Project Type:** Engineering Mathematics Mini Project + +**Technology:** Python, SymPy, NumPy, Matplotlib and Streamlit + +--- + +# 1. Abstract + +Gradient Explorer is an interactive mathematical visualisation project designed to demonstrate the concept of gradients and steepest ascent for functions of two variables. + +The project aims to help students understand how partial derivatives are used to calculate the gradient vector at a given point on a surface. It also aims to demonstrate gradient magnitude, direction and the relationship between gradients and contour lines. + +The application is being developed using Python and its mathematical libraries, with Streamlit providing the user interface. + +The current implementation includes a Streamlit interface and a safe mathematical equation parser. The mathematical calculation and visualisation modules are planned components of the project. + +# 2. Introduction + +Calculus plays an important role in engineering, mathematics and scientific applications. + +For functions of two variables, partial derivatives describe how a function changes with respect to one variable while keeping the other variable constant. + +The gradient combines these partial derivatives into a vector that indicates the direction of the greatest rate of increase of a function. + +Gradient Explorer aims to make this mathematical concept easier to understand through an interactive software application. + +# 3. Problem Statement + +Students often find it difficult to visualise how partial derivatives, gradient vectors and steepest ascent relate to a mathematical surface. + +Traditional mathematical calculations provide numerical answers but may not always make the geometric interpretation clear. + +The project aims to develop an interactive application that accepts mathematical functions and coordinates, calculates gradient properties and presents their graphical interpretation. + +# 4. Objectives + +The main objectives are: + +1. Develop an interactive mathematical application. +2. Accept functions of two variables, x and y. +3. Validate mathematical expressions safely. +4. Calculate partial derivatives. +5. Determine gradient vectors at selected points. +6. Calculate gradient magnitude and unit gradient vectors. +7. Visualise functions using heatmaps and contour plots. +8. Demonstrate the direction of steepest ascent. + +# 5. Mathematical Foundation + +## 5.1 Functions of Two Variables + +A function of two variables is represented as: + +f(x, y) + +It assigns a numerical value to each valid pair of input coordinates. + +## 5.2 Partial Derivatives + +The partial derivative with respect to x measures the rate of change of the function with respect to x while y remains constant. + +Similarly, the partial derivative with respect to y measures the rate of change with respect to y while x remains constant. + +## 5.3 Gradient Vector + +The gradient of a function is defined as: + +∇f(x,y) = (∂f/∂x, ∂f/∂y) + +It points in the direction of the steepest increase of the function. + +## 5.4 Gradient Magnitude + +The magnitude of the gradient is: + +|∇f| = √((∂f/∂x)² + (∂f/∂y)²) + +It represents the maximum rate of increase of the function at a point. + +## 5.5 Unit Gradient Vector + +The unit gradient vector is: + +u = ∇f / |∇f| + +It represents the direction of steepest ascent. + +This vector is undefined when the gradient magnitude is zero. + +# 6. Technology Stack + +| Technology | Application | +|---|---| +| Python | Main programming language | +| Streamlit | Interactive user interface | +| SymPy | Symbolic mathematics | +| NumPy | Numerical calculations | +| Matplotlib | Mathematical visualisation | +| Pytest | Automated testing | +| Git and GitHub | Version control and collaboration | +| GitHub Actions | Continuous integration | + +# 7. System Architecture + +The application follows a modular architecture. + +The planned modules include: + +- app.py: Main Streamlit application. +- equation_parser.py: Mathematical expression validation. +- calculations.py: Partial derivatives and gradient calculations. +- visualizations.py: Heatmaps, contour plots and gradient vectors. +- tests/: Automated testing. +- docs/: Technical and mathematical documentation. + +The intended workflow begins with user input, followed by equation validation, mathematical calculations and graphical visualisation. + +# 8. Implementation + +## 8.1 Streamlit Interface + +A basic Streamlit interface has been implemented to accept mathematical expressions and coordinate values. + +The interface includes: +- Mathematical equation input. +- X-coordinate input. +- Y-coordinate input. +- Calculate Gradient button. +- Equation validation feedback. + +## 8.2 Equation Parser + +A mathematical equation parser has been implemented using Python's Abstract Syntax Tree (AST) module and SymPy. + +It supports approved mathematical variables, constants, functions and operators. + +The parser uses an allowlist-based validation approach instead of directly evaluating arbitrary user input. + +## 8.3 Automated Testing + +Pytest is used to verify equation parsing and validation. + +The current parser test suite contains 14 tests covering: +- Basic mathematical expressions. +- Exponent notation. +- Supported mathematical functions. +- Mathematical constants. +- Invalid variables. +- Unsupported functions and operators. +- Invalid syntax. +- Unsafe input handling. +- Exponent restrictions. + +All 14 parser tests passed locally during development. + +## 8.4 Planned Implementation + +The following components remain under development: + +- Partial derivative calculations. +- Gradient magnitude and unit vector calculations. +- Heatmap and contour visualisations. +- Gradient arrow visualisation. +- Complete integration of mathematical and graphical modules. + +# 9. Testing and Validation + +The project uses automated tests to verify the correctness of its equation parser. + +A separate mathematical test specification has also been prepared to define expected results for the future gradient calculation engine. + +These mathematical test cases cover: +- Partial derivatives. +- Gradient components. +- Gradient magnitude. +- Unit gradient vectors. +- Zero-gradient conditions. +- Undefined and non-real results. + +The calculation engine will be tested against these expected mathematical results once implemented. + +# 10. Results and Discussion + +The current implementation demonstrates successful equation input and validation through the Streamlit interface. + +The parser has passed all 14 locally executed automated tests. + +The mathematical calculation and graphical visualisation stages are still under development. Therefore, final gradient calculation results and visualisation outputs are not yet available for evaluation. + +# 11. Limitations + +The current development stage has the following limitations: + +1. Gradient calculations are not yet integrated. +2. Heatmap and contour visualisations are pending. +3. Gradient vector arrows are pending. +4. Complete end-to-end application testing remains pending. + +# 12. Future Scope + +Potential improvements include: + +- Interactive three-dimensional surface visualisation. +- Directional derivative calculations. +- Interactive gradient vector controls. +- Additional mathematical functions. +- Improved graph customisation. +- Expanded mathematical test coverage. + +# 13. Conclusion + +Gradient Explorer is being developed as an interactive educational application to demonstrate gradients and steepest ascent for functions of two variables. + +The project has established its initial Streamlit interface, safe equation parsing system, automated parser tests and technical documentation. + +The remaining development work focuses on implementing the mathematical calculation engine, graphical visualisations and complete application integration. + +The project aims to provide students with a practical way to connect mathematical calculations with their geometric interpretation. + +# 14. References + +1. James Stewart, Calculus: Early Transcendentals. +2. SymPy Documentation – https://docs.sympy.org/ +3. Streamlit Documentation – https://docs.streamlit.io/ +4. NumPy Documentation – https://numpy.org/doc/ +5. Matplotlib Documentation – https://matplotlib.org/stable/ +6. Pytest Documentation – https://docs.pytest.org/