symbolic.hpp

浏览该文件的文档.

/**
 * @file symbolic.hpp
 * @brief 符号表达式主类 SymbolicExpr 及其工厂方法,运算接口.
 */
#pragma once
#define _USE_MATH_DEFINES
#include "lmcas_export.hpp"
#include "bigint.hpp"
#include "conditional_result.hpp"
#include "limit_value.hpp"
#include "rational.hpp"
#include <memory>
#include <string>
#include <variant>
#include <cmath>
#include <limits>
#include <algorithm>
#include <map>
#include <functional>
#include <stdexcept>
#include <type_traits>
 
namespace LMCAS {
 
class SymbolicExpr;
 
 
class AssumptionContext;
 
/** Result of an operation that produces a symbolic expression. */
using ExpressionResult = Result<std::shared_ptr<SymbolicExpr>>;
 
struct Binding {
    std::shared_ptr<SymbolicExpr> symbol;
    std::shared_ptr<SymbolicExpr> value;
};
 
/** @brief Stable relational operator used by public APIs. */
enum class RelationOp {
    EQ,
    NEQ,
    LT,
    GT,
    LEQ,
    GEQ
};
 
namespace detail {
struct SymbolicExprAccess;
} // namespace detail
 
/**
 * @brief 符号表达式主类,封装 AST 根节点并提供运算,化简,求解等接口.
 *
 * 通过静态工厂方法创建表达式,支持算术运算,三角函数,微积分,
 * 矩阵运算,方程求解等符号计算功能.
 */
class LMCAS_API SymbolicExpr : public std::enable_shared_from_this<SymbolicExpr> {
private:
    struct Impl;
    std::shared_ptr<const Impl> impl_;
 
    explicit SymbolicExpr(std::shared_ptr<const Impl> impl) : impl_(std::move(impl)) {
        if (!impl_) {
            throw std::invalid_argument("SymbolicExpr requires a non-null implementation");
        }
    }
 
    LMCAS::ExpressionResult factor_impl(
        LMCAS::ComputationContext& context) const;
 
    friend struct LMCAS::detail::SymbolicExprAccess;
 
public:
 
 
    SymbolicExpr() = delete;
 
    /**
     * @brief 与另一个表达式进行全序比较.
     * @param other 待比较的表达式
     * @return 小于返回负数,等于返回 0,大于返回正数
     */
    int compare(const std::shared_ptr<SymbolicExpr>& other) const;
 
 
    /** @brief 判断表达式是否为零. */
    bool is_zero() const;
    /** @brief 判断表达式是否为一. */
    bool is_one() const;
 
    /**
     * @brief 计算两个多项式关于指定变量的结式.
     * @param a 第一个多项式
     * @param b 第二个多项式
     * @param var 消去的变量名
     * @return 结式表达式
     */
    static std::shared_ptr<SymbolicExpr> poly_resultant(const std::shared_ptr<SymbolicExpr>& a, const std::shared_ptr<SymbolicExpr>& b, const std::string& var);
 
    /**
     * @brief 计算矩阵转置.
     * @param mat 矩阵表达式
     * @return 转置矩阵
     */
    static std::shared_ptr<SymbolicExpr> transpose(const std::shared_ptr<SymbolicExpr>& mat);
 
 
 
    /**
     * @brief 求解方程组(无参数变量版本).
     * @param equations 方程列表(每个表达式等于零)
     * @param vars 未知数变量名列表
     * @return 解的列表,每个解为变量名到表达式的映射
     */
    static std::vector<std::map<std::string, std::shared_ptr<SymbolicExpr>>> solve_system(
        const std::vector<std::shared_ptr<SymbolicExpr>>& equations,
        const std::vector<std::string>& vars);
 
    /**
     * @brief 求解含参数的方程组.
     * @param equations 方程列表(每个表达式等于零)
     * @param unknowns 未知数变量名列表
     * @param parameters 参数变量名列表
     * @return 解的列表,每个解为变量名到表达式的映射
     */
    static std::vector<std::map<std::string, std::shared_ptr<SymbolicExpr>>> solve_system(
        const std::vector<std::shared_ptr<SymbolicExpr>>& equations,
        const std::vector<std::string>& unknowns,
        const std::vector<std::string>& parameters);
 
    /**
     * @brief 在指定点展开为泰勒级数.
     * @param var 展开变量名
     * @param point 展开中心点
     * @param order 展开阶数
     * @param ctx 可选的假设上下文,用于验证收敛域和选择展开形式
     * @return 级数表达式
     */
    std::shared_ptr<SymbolicExpr> series(const std::string& var, const std::shared_ptr<SymbolicExpr>& point, int order, const LMCAS::AssumptionContext* ctx = nullptr) const;
 
    /**
     * @brief 执行符号除法.
     * @param num 被除数
     * @param den 除数
     * @return 商表达式
     */
    static std::shared_ptr<SymbolicExpr> divide(const std::shared_ptr<SymbolicExpr>& num, const std::shared_ptr<SymbolicExpr>& den);
 
    /**
     * @brief 创建积分表达式节点(不求值).
     * @param expr 被积表达式
     * @param var 积分变量名
     * @return 积分表达式
     */
    static std::shared_ptr<SymbolicExpr> make_integral(const std::shared_ptr<SymbolicExpr>& expr, const std::string& var);
 
    /**
     * @brief 创建极限表达式节点(不求值).
     * @param expr 表达式
     * @param var 趋近变量名
     * @param point 趋近目标值
     * @return 极限表达式
     */
    static std::shared_ptr<SymbolicExpr> make_limit(const std::shared_ptr<SymbolicExpr>& expr, const std::string& var, const std::shared_ptr<SymbolicExpr>& point);
 
    /**
     * @brief Factor this expression with explicit failure and budget reporting.
     */
    LMCAS::ExpressionResult factor_checked(
        LMCAS::ComputationContext& context) const;
    LMCAS::ExpressionResult factor_checked() const;
 
    /**
     * @brief 有理函数约分(消去分子分母公因式).
     *
     * 将表达式视为有理函数 P(x)/Q(x),计算 gcd(P, Q) 并约分.
     * 支持多元多项式(逐变量迭代 GCD).
     * 例如 (x^2-1)/(x-1) 约分为 x+1.
     *
     * @return 约分后的表达式
     */
    std::shared_ptr<SymbolicExpr> cancel() const;
 
 
    /**
     * @brief 创建整数数值表达式.
     * @param n 整数值
     * @return 数值表达式
     */
    static std::shared_ptr<SymbolicExpr> number(int n);
 
    /** @brief 较宽的整数值须显式转为 BigInt。 */
    template <typename Integer,
              std::enable_if_t<std::is_integral_v<Integer> &&
                               !std::is_same_v<Integer, int>, int> = 0>
    static std::shared_ptr<SymbolicExpr> number(Integer) = delete;
 
    static std::shared_ptr<SymbolicExpr> number(double n);
 
    /**
     * @brief 创建大整数数值表达式.
     * @param bi 大整数
     * @return 数值表达式
     */
    static std::shared_ptr<SymbolicExpr> number(const ::LMCAS::BigInt& bi);
 
    /**
     * @brief 创建有理数数值表达式.
     * @param r 有理数
     * @return 数值表达式
     */
    static std::shared_ptr<SymbolicExpr> number(const ::LMCAS::Rational& r);
 
    /**
     * @brief 创建无穷大表达式.
     * @param k 正数表示正无穷,负数表示负无穷
     * @return 无穷大表达式
     */
    static std::shared_ptr<SymbolicExpr> infinity(int k = 1);
 
    /**
     * @brief 创建平方根表达式,等价于 operand^(1/2).
     * @param operand 被开方数
     * @return 平方根表达式
     */
    static std::shared_ptr<SymbolicExpr> sqrt(std::shared_ptr<SymbolicExpr> operand);
 
    /**
     * @brief 创建乘法表达式.
     * @param left 左操作数
     * @param right 右操作数
     * @return 乘积表达式
     */
    static std::shared_ptr<SymbolicExpr> multiply(std::shared_ptr<SymbolicExpr> left, std::shared_ptr<SymbolicExpr> right);
 
    /**
     * @brief 创建加法表达式.
     * @param left 左操作数
     * @param right 右操作数
     * @return 和表达式
     */
    static std::shared_ptr<SymbolicExpr> add(std::shared_ptr<SymbolicExpr> left, std::shared_ptr<SymbolicExpr> right);
 
    /**
     * @brief 创建幂运算表达式.
     * @param base 底数
     * @param exponent 指数
     * @return 幂表达式
     */
    static std::shared_ptr<SymbolicExpr> power(std::shared_ptr<SymbolicExpr> base, std::shared_ptr<SymbolicExpr> exponent);
 
    /**
     * @brief 创建正弦函数表达式.
     * @param op 参数表达式
     * @return sin(op)
     */
    static std::shared_ptr<SymbolicExpr> sin(std::shared_ptr<SymbolicExpr> op);
 
    /**
     * @brief 创建余弦函数表达式.
     * @param op 参数表达式
     * @return cos(op)
     */
    static std::shared_ptr<SymbolicExpr> cos(std::shared_ptr<SymbolicExpr> op);
 
    /**
     * @brief 创建正切函数表达式.
     * @param op 参数表达式
     * @return tan(op)
     */
    static std::shared_ptr<SymbolicExpr> tan(std::shared_ptr<SymbolicExpr> op);
 
    /**
     * @brief 创建自然对数表达式.
     * @param op 参数表达式
     * @return ln(op)
     */
    static std::shared_ptr<SymbolicExpr> ln(std::shared_ptr<SymbolicExpr> op);
 
    /**
     * @brief 创建指数函数表达式 e^op.
     * @param op 指数参数
     * @return exp(op)
     */
    static std::shared_ptr<SymbolicExpr> exp(std::shared_ptr<SymbolicExpr> op);
 
    /**
     * @brief 创建 Lambert W 函数表达式.
     * @param op 参数表达式
     * @return W(op)
     */
    static std::shared_ptr<SymbolicExpr> lambertw(std::shared_ptr<SymbolicExpr> op);
 
    /**
     * @brief 创建以指定底数的对数表达式.
     * @param val 真数
     * @param base 底数
     * @return log_base(val)
     */
    static std::shared_ptr<SymbolicExpr> log(std::shared_ptr<SymbolicExpr> val, std::shared_ptr<SymbolicExpr> base);
 
    /**
     * @brief 创建双参数反正切表达式 atan2(y, x).
     * @param y y 坐标
     * @param x x 坐标
     * @return atan2 表达式
     */
    static std::shared_ptr<SymbolicExpr> atan2(std::shared_ptr<SymbolicExpr> y, std::shared_ptr<SymbolicExpr> x);
 
    /**
     * @brief 创建 RootOf 表达式,表示多项式的第 index 个根.
     * @param poly 多项式表达式
     * @param var 多项式变量名
     * @param index 根的索引
     * @return RootOf 表达式
     */
    static std::shared_ptr<SymbolicExpr> root_of(std::shared_ptr<SymbolicExpr> poly, const std::string& var, int index);
 
    /**
     * @brief 创建等式关系表达式 lhs = rhs.
     * @param lhs 左侧表达式
     * @param rhs 右侧表达式
     * @return 等式表达式
     */
    static std::shared_ptr<SymbolicExpr> eq(std::shared_ptr<SymbolicExpr> lhs, std::shared_ptr<SymbolicExpr> rhs);
 
    /**
     * @brief 从二维元素列表创建矩阵表达式.
     * @param elements 二维表达式数组,elements[i][j] 为第 i 行第 j 列元素
     * @return 矩阵表达式
     */
    static std::shared_ptr<SymbolicExpr> matrix(const std::vector<std::vector<std::shared_ptr<SymbolicExpr>>>& elements);
 
    /**
     * @brief 创建变量表达式.
     * @param name 变量名
     * @return 变量表达式
     */
    static std::shared_ptr<SymbolicExpr> variable(const std::string& name);
 
    /**
     * @brief 对表达式进行三角恒等式化简.
     * @return 化简后的表达式
     */
    std::shared_ptr<SymbolicExpr> simplify_trig() const;
 
    /**
     * @brief 将表达式转换为可读字符串.
     * @return 字符串表示
     */
    std::string to_string() const;
 
    /** @brief 判断表达式是否为数值节点. */
    bool is_number() const;
 
    /** @brief 判断表达式数值是否为零. */
    bool get_number_value_is_zero() const;
 
    /** @brief 判断表达式是否为大整数类型. */
    bool is_big_int() const;
 
    /** @brief 判断表达式是否为有理数类型. */
    bool is_rational() const;
 
    /** @brief 判断表达式是否为整数(包括 BigInt,整数 Rational,近似整数浮点). */
    bool is_int() const;
 
    /**
     * @brief 获取数值表达式的值.
     * @return 数值(int,BigInt 或 Rational)
     * @throws std::runtime_error 节点类型与数值访问器不匹配时抛出
     */
    std::variant<int, ::LMCAS::BigInt, ::LMCAS::Rational> get_number() const;
 
    int get_int() const;
    /**
     * @brief 获取大整数值.
     * @return BigInt 值
     * @throws std::runtime_error 节点类型与 BigInt 访问器不匹配时抛出
     */
    ::LMCAS::BigInt get_big_int() const;
    /**
     * @brief 获取有理数值.
     * @return Rational 值
     * @throws std::runtime_error 节点类型与 Rational 访问器不匹配时抛出
     */
    ::LMCAS::Rational get_rational() const;
    /**
     * @brief 将数值表达式转换为 Rational(BigInt 也会转换).
     * @return 有理数值,非数值类型返回 Rational(0)
     */
    ::LMCAS::Rational convert_rational() const;
 
    /**
     * @brief 将表达式求值为浮点数.
     * @return 数值结果
     */
    lmmc_real_t to_numeric() const;
};
 
} // namespace LMCAS