MathOS

Mathematical Research Platform

A comprehensive web-based computational platform for modern mathematics, featuring elliptic curve analysis, Galois theory, modular forms, topology, cryptography, and AI pattern recognition.

---

Table of Contents

• Overview
• Features
• Live Demo
• Installation
• Usage Guide
• API Documentation
• Technology Stack
• Project Structure
• Deployment
• Performance & Scaling
• Security
• Contributing
• License
• Acknowledgments
• Support

---

Overview

MathOS is a sophisticated mathematical research platform designed to provide researchers, students, and enthusiasts with powerful computational tools for exploring advanced mathematical concepts. Built with Python and Flask, it combines a user-friendly web interface with robust mathematical engines to deliver real-time analysis and visualization.

Purpose

Goal	Description
Research Support	Accelerate mathematical research with computational tools
Education	Provide an accessible platform for learning advanced mathematics
Experimentation	Enable rapid prototyping and testing of mathematical hypotheses
Collaboration	Share findings through a web-based interface

---

Features

Elliptic Curve Analysis

Click to expand details

Feature	Description
Curve Visualization	Analyze curves of the form y^2 = x^3 + ax + b
Rank Computation	Compute Mordell-Weil rank (exact or approximate)
Torsion Points	Identify torsion subgroups
Discriminant	Calculate discriminant and j-invariant
Group Structure	Analyze rational points structure

Example:

POST/api/curve
{
"a": 1,
"b": 1,
"exact_rank": true
}

Galois Theory

Click to expand details

Feature	Description
Galois Groups	Compute Galois groups of polynomials
Field Extensions	Analyze field extensions
Pre-built Examples	Common polynomials with known groups
Degree Analysis	Determine degree of field extensions

Supported Polynomials:

Polynomial	Galois Group
x^5 - 2	F_20 (Frobenius group)
x^4 + 1	V_4 (Klein four-group)
x^3 - 2	S_3 (Symmetric group)
x^5 - 4x + 2	S_5 (Symmetric group)

Example:

POST/api/galois
{
"polynomial": "x**5 - 2"
}

Modular Forms

Click to expand details

Feature	Description
Weight & Level	Compute forms of specified weight and level
L-Functions	Analyze associated L-functions
Fourier Coefficients	Generate and visualize coefficients
Eigenforms	Identify Hecke eigenforms

Example:

POST/api/modular
{
"weight": 2,
"level": 11
}

Topology

Click to expand details

Feature	Description
Homology Groups	Compute homology groups
Euler Characteristic	Calculate topological invariants
F-Vectors	Face vector analysis
Supported Spaces	Sphere, Torus, Projective Plane, Klein Bottle

Example:

POST/api/topology
{
"space": "torus",
"dimension": 2
}

Cryptography

Click to expand details

Feature	Description
Post-Quantum	Kyber and Dilithium benchmarks
ECC	Elliptic curve cryptography
Security Analysis	Lattice and ECC security evaluation
Key Generation	ECC key pair generation

Example:

POST/api/crypto
{
"action": "pqc"
}

AI Pattern Recognition

Click to expand details

Feature	Description
Sequence Identification	Identify Fibonacci, primes, squares
Recurrence Finding	Detect linear recurrences
Pattern Matching	Recognize mathematical patterns
Prediction	Extend sequences

Example:

POST/api/ai
{
"sequence": "1,1,2,3,5,8,13"
}

---

Live Demo

Visit the live application: mathos-ogx3.onrender.com

Note: Free tier may spin down after 15 minutes of inactivity. First request may take approximately 30 seconds to wake up.

---

Installation

Prerequisites

Requirement	Version
Python	3.7+
pip	Latest
git	Latest
Virtual Environment	Optional but recommended

Local Setup

1. Clone the Repository

git clone https://github.com/Soyebsoyeb/MathOS.git
cd MathOS

2. Create Virtual Environment

# Linux/Mac
python -m venv venv
source venv/bin/activate
# Windows
python -m venv venv
venv\Scripts\activate

3. Install Dependencies

pip install -r requirements.txt

4. Set Environment Variables

Create a .env file in the root directory:

SECRET_KEY=your-secret-key-hereFLASK_ENV=development

5. Run the Application

# Development mode
python math_research_platform/interfaces/web_app.py
# Production mode (using Gunicorn)
gunicorn --worker-class gthread --threads 4 --timeout 120 --bind 0.0.0.0:5000 math_research_platform.interfaces.web_app:app

6. Access the Application

Open your browser and navigate to: http://localhost:5000

Docker Deployment

# DockerfileFROM python:3.14-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
ENV SECRET_KEY=docker-secret-key
EXPOSE 5000
CMD ["gunicorn", "--worker-class", "gthread", "--threads", "4", "--timeout", "120", "--bind", "0.0.0.0:5000", "math_research_platform.interfaces.web_app:app"]

# Build and run
docker build -t mathos .
docker run -p 5000:5000 mathos

---

Usage Guide

Web Interface

The application provides a clean, dark-themed interface with the following modules:

1. Home Page

• Welcome screen with navigation
• Quick links to all modules
• Platform overview

2. Curves Module

• Input parameters a and b
• Compute exact or approximate rank
• View results in JSON format
• Quick examples for common curves

3. Galois Module

• Input polynomial expression
• Pre-built examples for common polynomials
• Detailed Galois group analysis

4. Modular Forms Module

• Set weight and level
• Compute form properties
• L-function analysis

5. Topology Module

• Select space type
• Set dimension
• Compute homology and Euler characteristic

6. Cryptography Module

• Select action type
• Benchmark post-quantum algorithms
• ECC operations

7. AI Module

• Input comma-separated sequences
• Identify sequence types
• Find recurrences

---

API Documentation

Base URL

https://mathos-ogx3.onrender.com/api

Authentication

No authentication required for public endpoints.

Endpoints

1. Elliptic Curve Analysis

POST /api/curve

Request Body:

{
"a": 1.0,
"b": 1.0,
"exact_rank": false
}

Response:

{
"status": "success",
"result": {
"curve": "y^2 = x^3 + 1.0x + 1.0",
"discriminant": -331,
"j_invariant": -3375/31,"rank": 1,
"torsion": "trivial"
}
}

2. Galois Theory

POST /api/galois

Request Body:

{
"polynomial": "x**5 - 2"
}

Response:

{
"status": "success",
"result": {
"polynomial": "x**5 - 2",
"degree": 5,
"galois_group": "F20",
"order": 20
}
}

3. Modular Forms

POST /api/modular

Request Body:

{
"weight": 2,
"level": 11
}

Response:

{
"status": "success",
"result": {
"weight": 2,
"level": 11,
"dimension": 1,
"coeffs": [0, 1, -2, -1, 2, 1, 2, -2, -1, 2, -2, -1]
}
}

4. Topology

POST /api/topology

Request Body:

{
"space": "torus",
"dimension": 2
}

Response:

{
"status": "success",
"result": {
"space": "torus",
"dimension": 2,
"euler_characteristic": 0,
"f_vector": [1, 4, 4, 1]
}
}

5. Cryptography

POST /api/crypto

Request Body:

{
"action": "benchmark"
}

Response:

{
"status": "success",
"result": {
"kyber": { "security": 128, "n": 256, "q": 3329 },
"dilithium": { "security": 256, "n": 256, "q": 8380417 }
}
}

6. AI Pattern Recognition

POST /api/ai

Request Body:

{
"sequence": "1,1,2,3,5,8,13"
}

Response:

{
"status": "success",
"result": {
"sequence": [1, 1, 2, 3, 5, 8, 13],
"identifications": ["Fibonacci sequence"],
"recurrences": {
"linear": "a(n) = a(n-1) + a(n-2)",
"order": 2
}
}
}

7. Health Check

GET /health

Response:

{
"status": "healthy",
"service": "MathOS",
"version": "1.0.0"
}

Error Handling

All endpoints return consistent error responses:

{
"status": "error",
"error": "Error message description"
}

HTTP Status Codes:

Code	Meaning
200	Success
400	Bad Request (invalid input)
500	Internal Server Error

---

Technology Stack

Backend

Technology	Version	Purpose
Python	3.14	Core language
Flask	3.1.3	Web framework
Gunicorn	26.0.0	Production WSGI server
SymPy	1.14	Symbolic mathematics
NumPy	2.5.1	Numerical computing
SciPy	1.18	Scientific computing
Flask-CORS	6.0.5	Cross-origin support

Frontend

Technology	Version	Purpose
Bootstrap	5.3.0	UI framework
Bootstrap Icons	1.10.0	Icon library
JavaScript	ES6	Client-side interactivity
HTML5	-	Structure
CSS3	-	Styling (custom dark theme)

Deployment

Technology	Purpose
Render.com	Cloud hosting
GitHub	Version control
Gunicorn	Production server

---

Project Structure

MathOS/
├── math_research_platform/
│ ├── interfaces/
│ │ └── web_app.py # Flask web interface (main app)
│ ├── main.py # Core platform module
│ ├── __init__.py # Package initializer
│ └── [other modules] # Future math modules
├── .gitignore # Git ignore rules
├── requirements.txt # Python dependencies
├── README.md # This file
├── LICENSE # MIT License
└── [configuration files] # Future config files

Key Files Explained

web_app.py

• Flask application entry point
• Contains all routes and API endpoints
• Implements health checks
• Uses main.py for mathematical computations
• Serves HTML pages with Bootstrap interface

main.py

• Core mathematical engine
• Contains all math computation functions
• Exposes platform object with all methods
• Handles elliptic curves, Galois theory, etc.

requirements.txt

• All Python dependencies
• Version-locked for stability
• Used by Render and local installations

---

Deployment

Deploy to Render (Recommended)

1. Create a Render Account

   • Visit render.com
   • Sign up with GitHub

2. Create New Web Service

   • Click "New +" -> "Web Service"
   • Connect your GitHub repository
   • Select Soyebsoyeb/MathOS

3. Configure Service

   Name: MathOSEnvironment: ProductionLanguage: Python 3Branch: mainRegion: Oregon (US West)

4. Set Build Settings

   Build Command: pip install -r requirements.txt
   Start Command: gunicorn --worker-class gthread --threads 4 --timeout 120 --bind 0.0.0.0:$PORT interfaces.web_app:app
   Root Directory: math_research_platform

5. Set Environment Variables

   SECRET_KEY = (generate random string)

6. Deploy

   • Click "Create Web Service"
   • Wait for build and deployment
   • Access at: https://mathos.onrender.com

Deploy to Heroku

# Install Heroku CLI
curl https://cli-assets.heroku.com/install.sh | sh
# Create App
heroku create mathos
heroku config:set SECRET_KEY=your-secret-key
git push heroku main
# Scale Dynos
heroku ps:scale web=1

Deploy to AWS EC2

# Launch Ubuntu Instance# SSH into Instance
ssh -i key.pem ubuntu@ec2-ip
# Install Dependencies
sudo apt update
sudo apt install python3-pip nginx -y
pip install -r requirements.txt
# Run with Gunicorn
gunicorn --worker-class gthread --threads 4 --timeout 120 --bind 0.0.0.0:8000 math_research_platform.interfaces.web_app:app

---

Performance & Scaling

Current Configuration

Parameter	Value	Purpose
Worker Class	gthread	Handles concurrent requests
Threads	4	Concurrent request handling
Timeout	120s	Long-running computations
Memory	512MB (free)	Sufficient for most operations
CPU	0.1 (free)	Single-core for computations

Optimization Tips

Caching

• Implement Redis cache for frequent computations
• Cache API responses for repeated queries

Asynchronous Processing

• Use Celery for long-running tasks
• Implement job queues

Database Integration

• Store computation results
• Cache historical queries

Load Balancing

• Use multiple workers
• Implement horizontal scaling

Performance Monitoring

# Add monitoring middleware@app.before_requestdefbefore_request():
request.start_time=time.time()
@app.after_requestdefafter_request(response):
elapsed=time.time() -request.start_timeprint(f"Request took {elapsed:.2f}s")
returnresponse

---

Security

Current Security Measures

Environment Variables

• SECRET_KEY stored in environment
• No hardcoded secrets

CORS Configuration

• Controlled cross-origin access
• Prevents unauthorized API access

Input Validation

• JSON request validation
• Type checking
• Bounds checking

Error Handling

• Proper exception handling
• No sensitive information in errors

Recommendations

Rate Limiting

fromflask_limiterimportLimiterlimiter=Limiter(app, key_func=lambda: request.remote_addr)
@app.route('/api/curve', methods=['POST'])@limiter.limit("10 per minute")defapi_curve():
# ...

HTTPS Enforce

fromflask_talismanimportTalismanTalisman(app)

Authentication

fromflask_jwt_extendedimportJWTManager, jwt_required# Add authentication to sensitive endpoints

---

Contributing

Ways to Contribute

Code Contributions

• New mathematical modules
• Performance improvements
• Bug fixes
• Test coverage

Documentation

• API documentation
• User guides
• Tutorials

UI/UX

• Responsive design improvements
• Accessibility enhancements
• Theme customizations

Development Workflow

1. Fork Repository

   git clone https://github.com/your-username/MathOS.git
   cd MathOS

2. Create Branch

   git checkout -b feature/AmazingFeature

3. Make Changes

   • Write code
   • Add tests
   • Update documentation

4. Test

   python -m pytest

5. Commit

   git add .
   git commit -m "Add some AmazingFeature"

6. Push

   git push origin feature/AmazingFeature

7. Create Pull Request

   • Open PR on GitHub
   • Describe changes
   • Wait for review

Code Style

• Python: PEP 8
• JavaScript: ESLint
• HTML/CSS: Bootstrap conventions

Testing

# test_mathos.pyimportunittestfrommath_research_platform.mainimportplatformclassTestMathOS(unittest.TestCase):
deftest_elliptic_curve(self):
result=platform.analyze_elliptic_curve(1, 1)
self.assertEqual(result['rank'], 1)
if__name__=='__main__':
unittest.main()

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License
Copyright (c) 2026 Soyebsoyeb
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

---

Acknowledgments

Libraries & Frameworks

• SymPy - Symbolic mathematics engine
• Flask - Web framework
• Bootstrap - UI components
• Gunicorn - Production server
• NumPy / SciPy - Scientific computing

Inspiration

• Mathematical research community
• Open source contributions
• Educational platforms

Contributors

• Soyebsoyeb - Creator and maintainer

Hosting

• Render.com - Free tier hosting

---

Support

Resources

Resource	Link
Live Demo	mathos-ogx3.onrender.com
GitHub Issues	Issues
Source Code	Repository
API Documentation	API Docs

Getting Help

1. Check Documentation - Read the README
2. Search Issues - Look for similar problems
3. Create Issue - Report bugs/feature requests
4. Contact - Reach out to maintainers

Common Issues

Issue	Cause	Solution
App Takes Long to Load	Free tier spin-down	Wait ~30 seconds for wake-up
ModuleNotFoundError	Missing dependencies	Run pip install -r requirements.txt
Port Already in Use	Another process on port 5000	Use different port or kill process
CORS Errors	Cross-origin restrictions	Use the API from allowed origins

---

Future Roadmap

Planned Features

• Graph Database - Store and query mathematical structures
• Jupyter Integration - Interactive notebooks
• Visualization - 3D plots and graphs
• Collaboration - Share and discuss results
• More Math Modules - Number theory, algebraic geometry
• Machine Learning - Automated theorem proving
• Mobile App - React Native version
• Cloud Storage - Save and load computations
• Export Options - PDF, LaTeX, Markdown
• Batch Processing - Run multiple computations

Version History

Version	Date	Changes
1.0.0	2026-07-19	Initial release
0.9.0	2026-07-15	Beta testing
0.8.0	2026-07-10	Alpha release

---

Made with passion and precision by Soyebsoyeb

Back to Top