diff --git a/README.md b/README.md index 7ae7f80..609f8ba 100644 --- a/README.md +++ b/README.md @@ -1,55 +1,49 @@ -# MaxMath（高代计算器 / Higher Algebra Calculator） +# MaxMath (Higher Algebra Calculator) [![CI](https://github.com/yueye6811/MaxMath/actions/workflows/ci.yml/badge.svg)](https://github.com/yueye6811/MaxMath/actions/workflows/ci.yml) [![Release](https://img.shields.io/github/v/release/yueye6811/MaxMath?label=release)](https://github.com/yueye6811/MaxMath/releases/latest) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) -[下载 MaxMath 1.0.0 APK / Download MaxMath 1.0.0 APK](https://github.com/yueye6811/MaxMath/releases/download/v1.0.0/MaxMath-v1.0.0-arm64-v8a.apk) -· [发布说明 / Release notes](https://github.com/yueye6811/MaxMath/releases/tag/v1.0.0) +

+ English | + 简体中文 +

-基于 GNU Maxima 的离线 Android 高等代数计算与交互式绘图应用。界面使用 -Kotlin 与 Jetpack Compose，数学输入由纯 Kotlin 解析器处理，复杂符号计算在独立 -引擎进程中执行。 +[Download MaxMath 1.0.0 APK](https://github.com/yueye6811/MaxMath/releases/download/v1.0.0/MaxMath-v1.0.0-arm64-v8a.apk) +· [Release notes](https://github.com/yueye6811/MaxMath/releases/tag/v1.0.0) MaxMath is an offline Android app for higher-algebra computation and interactive plotting, powered by GNU Maxima. Its interface is built with Kotlin and Jetpack Compose, mathematical input is handled by a pure Kotlin parser, and complex symbolic computations run in a separate engine process. -> **中文：** 当前版本 1.0.0；最低系统 Android 8.0（API 26）；原生计算引擎目前仅提供 -> `arm64-v8a` 构建流程。 -> -> **English:** Current release: 1.0.0. Minimum supported version: Android 8.0 -> (API 26). The native computation engine currently provides an `arm64-v8a` -> build workflow only. - -## 功能 / Features - -- **矩阵 / Matrices：** 行列式、逆、转置、秩、迹、特征值与特征向量 / determinant, inverse, transpose, rank, trace, eigenvalues, and eigenvectors -- **方程组 / Systems of equations：** 支持 `x+y=1; 2x-y=3` 一类自然写法，也支持原始 Maxima 输入 / natural syntax such as `x+y=1; 2x-y=3`, plus raw Maxima input -- **多项式 / Polynomials：** 因式分解、最大公因式、求根、展开与化简 / factorization, greatest common divisor, root finding, expansion, and simplification -- **向量空间 / Vector spaces：** 内积、范数、Gram-Schmidt 正交化 / inner product, norm, and Gram-Schmidt orthogonalization -- **二次型 / Quadratic forms：** 展开、特征值与符号差 / expansion, eigenvalues, and signature -- **微积分 / Calculus：** 极限、任意阶导数、定积分与不定积分 / limits, derivatives of arbitrary order, and definite or indefinite integrals -- **绘图 / Plotting：** 支持触控交互的 2D 多函数图像、3D 曲面和等高线 / touch-enabled 2D multi-function plots, 3D surfaces, and contour plots -- **输入 / Input：** 隐式乘法、根号、分数、常用函数、π/e 与自然写法方程组 / implicit multiplication, radicals, fractions, common functions, π/e, and natural equation syntax -- **输出 / Output：** 离线 LaTeX 渲染、可复制文本，并可保存或分享 PNG / offline LaTeX rendering, copyable text, and PNG saving or sharing -- **本地化 / Localization：** 中文、English、跟随系统 / Chinese, English, or the system language -- **隐私 / Privacy：** 不申请网络权限，不包含账号、广告、分析或遥测 / no network permission, accounts, ads, analytics, or telemetry - -## 架构 / Architecture - -| 路径 / Path | 职责 / Responsibility | -| --- | --- | -| `parser/` | 词法分析、AST、表达式求值，以及 Maxima/NumPy 代码生成
Lexing, AST construction, expression evaluation, and Maxima/NumPy code generation | -| `engine/` | 类型化计算任务、Maxima 脚本、JNI 子进程、独立进程服务和 2D 绘图
Typed computation tasks, Maxima scripts, JNI subprocesses, the isolated process service, and 2D plotting | -| `app/` | Compose 页面、状态管理、LaTeX 输出及 OpenGL 3D/等高线交互
Compose screens, state management, LaTeX output, and interactive OpenGL 3D/contour rendering | -| `native/` | ECL 与 Maxima 的 Android 交叉编译和运行时打包脚本
Android cross-compilation and runtime packaging scripts for ECL and Maxima | -| `docs/` | 产品规格与实现约束
Product specifications and implementation constraints | +> Current release: 1.0.0. Minimum supported version: Android 8.0 (API 26). +> The native computation engine currently provides an `arm64-v8a` build +> workflow only. + +## Features + +- Matrices: determinant, inverse, transpose, rank, trace, eigenvalues, and eigenvectors +- Systems of equations: natural syntax such as `x+y=1; 2x-y=3`, plus raw Maxima input +- Polynomials: factorization, greatest common divisor, root finding, expansion, and simplification +- Vector spaces: inner product, norm, and Gram-Schmidt orthogonalization +- Quadratic forms: expansion, eigenvalues, and signature +- Calculus: limits, derivatives of arbitrary order, and definite or indefinite integrals +- Plotting: touch-enabled 2D multi-function plots, 3D surfaces, and contour plots +- Input: implicit multiplication, radicals, fractions, common functions, π/e, and natural equation syntax +- Output: offline LaTeX rendering, copyable text, and PNG saving or sharing +- Localization: Chinese, English, or the system language +- Privacy: no network permission, accounts, ads, analytics, or telemetry -轻量操作在 UI 进程执行；耗时操作通过 Android Messenger 转发到 `:engine` 独立 -进程。取消或超时会终止对应的 Maxima 子进程。2D 图像由 Maxima 辅助分析并交给 -Matplotlib 渲染；3D 曲面和等高线由同一表达式 AST 在本地采样并交给 OpenGL 绘制。 +## Architecture + +| Path | Responsibility | +| --- | --- | +| `parser/` | Lexing, AST construction, expression evaluation, and Maxima/NumPy code generation | +| `engine/` | Typed computation tasks, Maxima scripts, JNI subprocesses, the isolated process service, and 2D plotting | +| `app/` | Compose screens, state management, LaTeX output, and interactive OpenGL 3D/contour rendering | +| `native/` | Android cross-compilation and runtime packaging scripts for ECL and Maxima | +| `docs/` | Product specifications and implementation constraints | Lightweight operations run in the UI process. Long-running work is forwarded through Android Messenger to the isolated `:engine` process. Cancellation or a @@ -57,54 +51,47 @@ timeout terminates the corresponding Maxima subprocess. Maxima assists with 2D plot analysis before Matplotlib renders the image; 3D surfaces and contour plots are sampled locally from the same expression AST and rendered with OpenGL. -## 获取源码 / Getting the Source +## Getting the Source ~~~bash git clone https://github.com/yueye6811/MaxMath.git cd MaxMath ~~~ -### 环境要求 / Requirements +### Requirements - JDK 17 -- Android Studio，或 / or Android SDK 36 -- Android NDK 27.2.12479018 与 / and CMake 3.22（编译 JNI 桥时需要 / required to compile the JNI bridge） -- Python 3.10（Chaquopy 打包 Python 运行时依赖时需要 / required when Chaquopy packages Python runtime dependencies） - -SDK 的本机路径应放在未跟踪的 `local.properties` 中。仓库不包含任何签名密钥； -发布签名配置请写入未跟踪的 `keystore.properties`。 +- Android Studio, or Android SDK 36 +- Android NDK 27.2.12479018 and CMake 3.22 (required to compile the JNI bridge) +- Python 3.10 (required when Chaquopy packages Python runtime dependencies) Put the local SDK path in the untracked `local.properties` file. The repository does not contain signing keys; place release-signing configuration in the untracked `keystore.properties` file. -### 运行测试 / Running Tests +### Running Tests ~~~bash ./gradlew :parser:test ./gradlew -Pmaxmath.buildNative=false :engine:testDebugUnitTest :app:testDebugUnitTest ~~~ -Windows 下请使用 / On Windows, use: +On Windows, use: ~~~cmd gradlew.bat :parser:test gradlew.bat -Pmaxmath.buildNative=false :engine:testDebugUnitTest :app:testDebugUnitTest ~~~ -### 构建 Android 应用 / Building the Android App +### Building the Android App ~~~bash ./gradlew :app:assembleDebug ~~~ -输出位于 / The APK is written to `app/build/outputs/apk/debug/app-debug.apk`. - -## 原生 Maxima 引擎 / Native Maxima Engine +The APK is written to `app/build/outputs/apk/debug/app-debug.apk`. -Maxima/ECL 的下载目录、交叉编译产物和生成后的应用运行时文件体积较大，并受各自 -许可证约束，因此默认不纳入 Git。源码检出后可以先编译和安装 UI，但实际 Maxima -计算需要先生成并打包原生引擎： +## Native Maxima Engine The Maxima/ECL download directories, cross-compilation outputs, and generated application runtime are large and governed by their respective licenses, so they @@ -122,46 +109,37 @@ cd .. ./gradlew :app:assembleDebug ~~~ -当前脚本以 Linux x86_64 主机和 NDK 的 `linux-x86_64` 工具链为目标。完整依赖、 -环境变量与故障说明见 [native/README.md](native/README.md)。 - The current scripts target a Linux x86_64 host and the NDK's `linux-x86_64` toolchain. See [native/README.md](native/README.md) for complete dependency, environment-variable, and troubleshooting information. -生成但不提交的目录 / Generated directories that must not be committed: +Generated directories that must not be committed include: - `.build/` - `app/src/main/assets/engine/` - `app/src/main/jniLibs/` -## 项目文档 / Project Documentation +## Project Documentation -- [产品与实现规格 / Product and implementation specification](docs/SPEC.md) -- [原生引擎构建 / Native engine build guide](native/README.md) -- [发布说明 / Release notes](RELEASE_NOTES.md) -- [贡献指南 / Contributing guide](CONTRIBUTING.md) -- [安全策略 / Security policy](SECURITY.md) -- [隐私说明 / Privacy notice](PRIVACY.md) -- [第三方许可证说明 / Third-party license notices](THIRD_PARTY_NOTICES.md) +- [Product and implementation specification](docs/SPEC.md) +- [Native engine build guide](native/README.md) +- [Release notes](RELEASE_NOTES.md) +- [Contributing guide](CONTRIBUTING.md) +- [Security policy](SECURITY.md) +- [Privacy notice](PRIVACY.md) +- [Third-party license notices](THIRD_PARTY_NOTICES.md) -## 已知限制 / Known Limitations +## Known Limitations -- 原生计算引擎当前只面向 `arm64-v8a`；`x86_64` 构建脚本仍需进一步验证。 / The native computation engine currently targets `arm64-v8a` only; the `x86_64` build scripts still need further verification. -- 新检出的源码仓库不含预编译 Maxima/ECL 运行时，必须按上文生成后才能执行完整计算。 / A fresh source checkout does not include a prebuilt Maxima/ECL runtime. Generate it as described above before running full computations. -- 计算结果来自计算机代数与数值算法，不应被视为形式化证明。 / Results come from computer algebra and numerical algorithms and should not be treated as formal proofs. +- The native computation engine currently targets `arm64-v8a` only; the `x86_64` build scripts still need further verification. +- A fresh source checkout does not include a prebuilt Maxima/ECL runtime. Generate it as described above before running full computations. +- Results come from computer algebra and numerical algorithms and should not be treated as formal proofs. -## 许可证 / License - -MaxMath 贡献者原创、且没有独立许可证声明的源代码采用 [MIT License](LICENSE)。 +## License Source code contributed to MaxMath that is original to the project and does not carry a separate license notice is licensed under the [MIT License](LICENSE). -构建会解析 GPL-2.0 的 `jlatexmath-android`，并可包含 GPL 的 GNU Maxima；ECL、 -Chaquopy、Matplotlib、NumPy 等组件也保留各自许可证。分发完整 APK 时必须履行 -这些第三方许可证的义务。详情见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。 - The build resolves the GPL-2.0-licensed `jlatexmath-android` and may include the GPL-licensed GNU Maxima. ECL, Chaquopy, Matplotlib, NumPy, and other components also retain their respective licenses. Distribution of a complete APK must diff --git a/README.zh-CN.md b/README.zh-CN.md new file mode 100644 index 0000000..2ff825f --- /dev/null +++ b/README.zh-CN.md @@ -0,0 +1,137 @@ +# MaxMath（高代计算器） + +[![CI](https://github.com/yueye6811/MaxMath/actions/workflows/ci.yml/badge.svg)](https://github.com/yueye6811/MaxMath/actions/workflows/ci.yml) +[![Release](https://img.shields.io/github/v/release/yueye6811/MaxMath?label=release)](https://github.com/yueye6811/MaxMath/releases/latest) +[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) + +

+ English | + 简体中文 +

+ +[下载 MaxMath 1.0.0 APK](https://github.com/yueye6811/MaxMath/releases/download/v1.0.0/MaxMath-v1.0.0-arm64-v8a.apk) +· [发布说明](https://github.com/yueye6811/MaxMath/releases/tag/v1.0.0) + +基于 GNU Maxima 的离线 Android 高等代数计算与交互式绘图应用。界面使用 +Kotlin 与 Jetpack Compose，数学输入由纯 Kotlin 解析器处理，复杂符号计算在独立 +引擎进程中执行。 + +> 当前版本 1.0.0；最低系统 Android 8.0（API 26）；原生计算引擎目前仅提供 +> `arm64-v8a` 构建流程。 + +## 功能 + +- 矩阵：行列式、逆、转置、秩、迹、特征值与特征向量 +- 方程组：支持 `x+y=1; 2x-y=3` 一类自然写法，也支持原始 Maxima 输入 +- 多项式：因式分解、最大公因式、求根、展开与化简 +- 向量空间：内积、范数、Gram-Schmidt 正交化 +- 二次型：展开、特征值与符号差 +- 微积分：极限、任意阶导数、定积分与不定积分 +- 绘图：2D 多函数图像、3D 曲面和等高线，支持触控交互 +- 输入：隐式乘法、根号、分数、常用函数、π/e 与自然写法方程组 +- 输出：离线 LaTeX 渲染，可复制文本，并可保存或分享 PNG +- 本地化：中文、English、跟随系统 +- 隐私：不申请网络权限，不包含账号、广告、分析或遥测 + +## 架构 + +| 路径 | 职责 | +| --- | --- | +| `parser/` | 词法分析、AST、表达式求值，以及 Maxima/NumPy 代码生成 | +| `engine/` | 类型化计算任务、Maxima 脚本、JNI 子进程、独立进程服务和 2D 绘图 | +| `app/` | Compose 页面、状态管理、LaTeX 输出及 OpenGL 3D/等高线交互 | +| `native/` | ECL 与 Maxima 的 Android 交叉编译和运行时打包脚本 | +| `docs/` | 产品规格与实现约束 | + +轻量操作在 UI 进程执行；耗时操作通过 Android Messenger 转发到 `:engine` 独立 +进程。取消或超时会终止对应的 Maxima 子进程。2D 图像由 Maxima 辅助分析并交给 +Matplotlib 渲染；3D 曲面和等高线由同一表达式 AST 在本地采样并交给 OpenGL 绘制。 + +## 获取源码 + +~~~bash +git clone https://github.com/yueye6811/MaxMath.git +cd MaxMath +~~~ + +### 环境要求 + +- JDK 17 +- Android Studio，或 Android SDK 36 +- Android NDK 27.2.12479018 与 CMake 3.22（编译 JNI 桥时需要） +- Python 3.10（Chaquopy 打包 Python 运行时依赖时需要） + +SDK 的本机路径应放在未跟踪的 `local.properties` 中。仓库不包含任何签名密钥； +发布签名配置请写入未跟踪的 `keystore.properties`。 + +### 运行测试 + +~~~bash +./gradlew :parser:test +./gradlew -Pmaxmath.buildNative=false :engine:testDebugUnitTest :app:testDebugUnitTest +~~~ + +Windows 下请使用： + +~~~cmd +gradlew.bat :parser:test +gradlew.bat -Pmaxmath.buildNative=false :engine:testDebugUnitTest :app:testDebugUnitTest +~~~ + +### 构建 Android 应用 + +~~~bash +./gradlew :app:assembleDebug +~~~ + +输出位于 `app/build/outputs/apk/debug/app-debug.apk`。 + +## 原生 Maxima 引擎 + +Maxima/ECL 的下载目录、交叉编译产物和生成后的应用运行时文件体积较大，并受各自 +许可证约束，因此默认不纳入 Git。源码检出后可以先编译和安装 UI，但实际 Maxima +计算需要先生成并打包原生引擎： + +~~~bash +cd native +./download-sources.sh +./build-host-ecl.sh +./build-ecl-android.sh arm64-v8a +./build-maxima-android.sh arm64-v8a +./package-engine.sh arm64-v8a +cd .. +./gradlew :app:assembleDebug +~~~ + +当前脚本以 Linux x86_64 主机和 NDK 的 `linux-x86_64` 工具链为目标。完整依赖、 +环境变量与故障说明见 [native/README.md](native/README.md)。 + +生成但不提交的目录包括： + +- `.build/` +- `app/src/main/assets/engine/` +- `app/src/main/jniLibs/` + +## 项目文档 + +- [产品与实现规格](docs/SPEC.md) +- [原生引擎构建](native/README.md) +- [发布说明](RELEASE_NOTES.md) +- [贡献指南](CONTRIBUTING.md) +- [安全策略](SECURITY.md) +- [隐私说明](PRIVACY.md) +- [第三方许可证说明](THIRD_PARTY_NOTICES.md) + +## 已知限制 + +- 原生计算引擎当前只面向 `arm64-v8a`；`x86_64` 构建脚本仍需进一步验证。 +- 新检出的源码仓库不含预编译 Maxima/ECL 运行时，必须按上文生成后才能执行完整计算。 +- 计算结果来自计算机代数与数值算法，不应被视为形式化证明。 + +## 许可证 + +MaxMath 贡献者原创、且没有独立许可证声明的源代码采用 [MIT License](LICENSE)。 + +构建会解析 GPL-2.0 的 `jlatexmath-android`，并可包含 GPL 的 GNU Maxima；ECL、 +Chaquopy、Matplotlib、NumPy 等组件也保留各自许可证。分发完整 APK 时必须履行 +这些第三方许可证的义务。详情见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。