diff --git a/README.md b/README.md index 0a7a38a..7ae7f80 100644 --- a/README.md +++ b/README.md @@ -1,88 +1,116 @@ -# MaxMath（高代计算器） +# 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) -[![License: MIT](https://img.shields.io/badge/原创代码-MIT-blue.svg)](LICENSE) +[![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) 基于 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、跟随系统 -- 隐私：不申请网络权限，不包含账号、广告、分析或遥测 - -## 架构 - -| 路径 | 职责 | +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 代码生成 | -| engine/ | 类型化计算任务、Maxima 脚本、JNI 子进程、独立进程服务和 2D 绘图 | -| app/ | Compose 页面、状态管理、LaTeX 输出及 OpenGL 3D/等高线交互 | -| native/ | ECL 与 Maxima 的 Android 交叉编译和运行时打包脚本 | -| docs/ | 产品规格与实现约束 | +| `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 | -轻量操作在 UI 进程执行；耗时操作通过 Android Messenger 转发到 :engine 独立 +轻量操作在 UI 进程执行；耗时操作通过 Android Messenger 转发到 `:engine` 独立 进程。取消或超时会终止对应的 Maxima 子进程。2D 图像由 Maxima 辅助分析并交给 Matplotlib 渲染；3D 曲面和等高线由同一表达式 AST 在本地采样并交给 OpenGL 绘制。 -## 获取源码 +Lightweight operations run in the UI process. Long-running work is forwarded +through Android Messenger to the isolated `:engine` process. Cancellation or a +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 ~~~bash git clone https://github.com/yueye6811/MaxMath.git cd MaxMath ~~~ -### 环境要求 +### 环境要求 / Requirements - JDK 17 -- Android Studio，或 Android SDK 36 -- Android NDK 27.2.12479018 与 CMake 3.22（编译 JNI 桥时需要） -- Python 3.10（Chaquopy 打包 Python 运行时依赖时需要） +- 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。 +SDK 的本机路径应放在未跟踪的 `local.properties` 中。仓库不包含任何签名密钥； +发布签名配置请写入未跟踪的 `keystore.properties`。 -### 运行测试 +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 ~~~bash ./gradlew :parser:test ./gradlew -Pmaxmath.buildNative=false :engine:testDebugUnitTest :app:testDebugUnitTest ~~~ -Windows 下请使用： +Windows 下请使用 / On Windows, use: ~~~cmd gradlew.bat :parser:test gradlew.bat -Pmaxmath.buildNative=false :engine:testDebugUnitTest :app:testDebugUnitTest ~~~ -### 构建 Android 应用 +### 构建 Android 应用 / Building the Android App ~~~bash ./gradlew :app:assembleDebug ~~~ -输出位于 app/build/outputs/apk/debug/app-debug.apk。 +输出位于 / The APK is written to `app/build/outputs/apk/debug/app-debug.apk`. -## 原生 Maxima 引擎 +## 原生 Maxima 引擎 / Native Maxima Engine Maxima/ECL 的下载目录、交叉编译产物和生成后的应用运行时文件体积较大，并受各自 许可证约束，因此默认不纳入 Git。源码检出后可以先编译和安装 UI，但实际 Maxima 计算需要先生成并打包原生引擎： +The Maxima/ECL download directories, cross-compilation outputs, and generated +application runtime are large and governed by their respective licenses, so they +are not tracked by Git. A fresh checkout can build and install the UI, but actual +Maxima computation requires generating and packaging the native engine first: + ~~~bash cd native ./download-sources.sh @@ -94,35 +122,48 @@ cd .. ./gradlew :app:assembleDebug ~~~ -当前脚本以 Linux x86_64 主机和 NDK 的 linux-x86_64 工具链为目标。完整依赖、 +当前脚本以 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: -- .build/ -- app/src/main/assets/engine/ -- app/src/main/jniLibs/ +- `.build/` +- `app/src/main/assets/engine/` +- `app/src/main/jniLibs/` -## 项目文档 +## 项目文档 / Project Documentation -- [产品与实现规格](docs/SPEC.md) -- [原生引擎构建](native/README.md) -- [发布说明](RELEASE_NOTES.md) -- [贡献指南](CONTRIBUTING.md) -- [安全策略](SECURITY.md) -- [隐私说明](PRIVACY.md) -- [第三方许可证说明](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 -- 原生计算引擎当前只面向 arm64-v8a；x86_64 构建脚本仍需进一步验证。 -- 新检出的源码仓库不含预编译 Maxima/ECL 运行时，必须按上文生成后才能执行完整计算。 -- 计算结果来自计算机代数与数值算法，不应被视为形式化证明。 +- 原生计算引擎当前只面向 `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. -## 许可证 +## 许可证 / License MaxMath 贡献者原创、且没有独立许可证声明的源代码采用 [MIT License](LICENSE)。 -构建会解析 GPL-2.0 的 jlatexmath-android，并可包含 GPL 的 GNU Maxima；ECL、 +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 +comply with those third-party license obligations. See +[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for details.