Skip to content

docs.md

Latest commit

 

History

History
497 lines (363 loc) · 9.73 KB

docs.md

File metadata and controls

497 lines (363 loc) · 9.73 KB
Raw

MathOS Documentation

A comprehensive guide to the MathOS Mathematical Research Platform.

Quick Links

Resource Link
Live Demo mathos-ogx3.onrender.com
GitHub Issues github.com/Soyebsoyeb/MathOS/issues
Source Code github.com/Soyebsoyeb/MathOS
API Documentation mathos-ogx3.onrender.com/api

Table of Contents

Getting Help

  1. Check Documentation - Read the README and this docs file
  2. Search Issues - Look for similar problems on GitHub Issues
  3. Create Issue - Report bugs or request features at github.com/Soyebsoyeb/MathOS/issues/new
  4. Contact - Reach out to the maintainer via GitHub

Common Issues

Issue Cause Solution
App Takes Long to Load Free tier spin-down on Render Wait approximately 30 seconds for wake-up
ModuleNotFoundError Missing Python dependencies Run pip install -r requirements.txt
Port Already in Use Another process on port 5000 Use a different port or kill the existing process
CORS Errors Cross-origin restrictions Use the API from allowed origins
Timeout Errors Computation exceeds 120s Reduce complexity or upgrade server resources
Invalid JSON Response Malformed request body Validate JSON syntax before sending

API Reference

Base URL

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

Authentication

No authentication required for public endpoints.

Endpoints

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"
  }
}
Parameter Type Required Description
a float Yes Curve parameter a
b float Yes Curve parameter b
exact_rank boolean No Compute exact rank (default: false)

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
  }
}
Parameter Type Required Description
polynomial string Yes Polynomial expression in x

Supported Polynomials:

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

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]
  }
}
Parameter Type Required Description
weight integer Yes Weight of the modular form
level integer Yes Level of the modular form

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]
  }
}
Parameter Type Required Description
space string Yes Space type: sphere, torus, projective_plane, klein_bottle
dimension integer No Dimension (default: 2)

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 }
  }
}
Parameter Type Required Description
action string Yes Action type: benchmark, keygen, security, pqc

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
    }
  }
}
Parameter Type Required Description
sequence string Yes Comma-separated sequence of numbers

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

Deployment Guide

Deploy to Render (Recommended)

  1. Create a Render account at render.com
  2. Click "New +" -> "Web Service"
  3. Connect your GitHub repository Soyebsoyeb/MathOS
  4. Configure the service:
Name: MathOS
Environment: Production
Language: Python 3
Branch: main
Region: Oregon (US West)
  1. 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
  1. Set environment variables:
SECRET_KEY = (generate a random string)
  1. Click "Create Web Service" and wait for deployment

Deploy to Heroku

# Install Heroku CLI
curl https://cli-assets.heroku.com/install.sh | sh

# Create and configure 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

# 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

Docker Deployment

FROM 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"]
docker build -t mathos .
docker run -p 5000:5000 mathos

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 and clone
git clone https://github.com/your-username/MathOS.git
cd MathOS

# 2. Create branch
git checkout -b feature/AmazingFeature

# 3. Make changes and test
python -m pytest

# 4. Commit and push
git add .
git commit -m "Add some AmazingFeature"
git push origin feature/AmazingFeature

# 5. Create Pull Request on GitHub

Code Style

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

License

This project is licensed under the MIT License.

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.

Resources

Resource Link
Live Demo mathos-ogx3.onrender.com
GitHub Issues github.com/Soyebsoyeb/MathOS/issues
Source Code github.com/Soyebsoyeb/MathOS
API Documentation mathos-ogx3.onrender.com/api

MathOS Documentation | Maintained by Soyebsoyeb