README

PHPMathObjects库是为考虑晶体学应用而创建的，但应适用于各种项目。该库具有100%的单元测试覆盖率，且经过性能优化。由于它正在积极开发中，因此目前不适合生产环境，因为当前的API可能会发生变化。

安装

使用Composer安装PHPMathObjects

composer require sivlev/phpmathobjects

或者在您的composer.json文件中包含以下行

"sivlev/phpmathobjects": "*"

需求

该库需要PHP 8.2或更高版本。不需要其他外部依赖。

如何使用

本节包含PHPMathObjects API方法的简化列表。为了清晰起见，省略了一些具有默认值的参数。有关完整API参考，请参阅docs。

内容

• 通用数学

  • 数学

• 线性代数

  • 矩阵
  • 向量

• 数字

  • 有理数

通用数学

数学

Math类包含可能在各个领域需要的常用数学函数。这些函数以静态方法的形式实现。

// Check if the number equals zero within the given tolerance
$isZero = Math::isZero(0.000002);                       // Returns false
$isZero = Math::isZero(0.000002, 1e-3);                 // Returns true

// Check if the number does not equal zero within the given tolerance
$isNotZero = Math::isNotZero(0.000002);                 // Returns true
$isNotZero = Math::isNotZero(0.000002, 1e-3);           // Returns false

// Check if two numbers are equal within the given tolerance
$areEqual = Math::areEqual(0.000002, 0.000003);         // Returns false
$areEqual = Math::areEqual(0.000002, 0.000003, 1e-3);   // Returns true

// Compare two numeric arrays elementwise within the given tolerance
$areEqual = Math::areArraysEqual([1, 2, 3], [1, 2, 3]); // Returns true

// Find the greatest common divisor of two numbers
$gcd = Math::gcd(28, 35);       // Returns 7

线性代数

矩阵

PHPMathObjects中的许多矩阵方法以两种版本实现：非变异（返回新的矩阵对象）和变异（更改现有矩阵）。后者的方法名称以字母“m”开头，例如add()和mAdd()，transpose()和mTranspose()等。您可以根据特定任务选择哪种方法更合适。通常，变异方法比非变异方法略快，因为不需要创建新的对象实例。

// Create a new matrix object using class constructor
$matrix = new Matrix([
    [1, 2, 3],
    [4, 5, 6],
    [7, 8, 9],
]);

// Or use a suitable factory method
$matrix = Matrix::fill(3, 4, 0.1);          // Make a 3x4 matrix and fill its elements with 0.1
$matrix = Matrix::identity(3);              // Make a 3x3 identity matrix
$matrix = Matrix::random(5, 8, -3.5, 9.5)   // Make a 5x8 matrix filled with random float numbers between -3.5 and 9.5
$matrix = Matrix::randomInt(3, 3, 1, 10)    // Make a 3x3 matrix filled with random integer numbers between 1 and 10

// Matrix dimensions
$rows = $matrix->rows();
$columns = $matrix->columns();
$numberOfElements = $matrix->size(); 
$numberOfElements = count($matrix);         // Alternative way as Matrix implements "Countable" interface

// Get matrix as array
$array = $matrix->toArray(); 

// Element getters and setters (zero-based indexing)
$element = $matrix->get(1, 2);
$matrix->set(1, 2, -15.6);
$element = $matrix->set(1, 2, 100)->get(1, 2); // Set() method returns $this so it can be chained
$doesElementExist = $matrix->isSet(2, 1);

// Alternative getters and setters via "ArrayAccess" interface
$element = $matrix[[1, 2]];    // Note the format of the index. The problem is that PHP supports native ArrayAccess for 1D arrays only
$matrix[[1, 2]] = 15;
$doesElementExist = isset($matrix[[1, 2]]);

// Matrix properties
$isSquare = $matrix->isSquare(); 

// Compare matrices
$equal = $matrix->isEqual($anotherMatrix);          // Compare elementwise within a default tolerance of 1.0e^-8
$equal = $matrix->isEqual($anotherMatrix, 1e-8);    // Or set the tolerance explicitly
$equal = $matrix->isEqualExactly($anotherMatrix);   // Compare matrices elementwise with '===' operator

// Check if the matrix has zero elements only
$isZero = $matrix->isZero($tolerance);              // Check if zero elementwise within the given tolerance (default is 1.0e^-8)
$isZeroExactly = $matrix->isZeroExactly();          // Check if zero elementwise exactly using the '===' operator

// Matrix arithmetics
$sum = $matrix->add($anotherMatrix);
$difference = $matrix->subtract($anotherMatrix);
$multiplication = $matrix->multiply($anotherMatrix);
$multiplicationByScalar = $matrix->multiplyByScalar($scalarIntOrFloat);
$signsChanged = $matrix->changeSign();

// Matrix arithmetics (mutating methods)
$matrix->mAdd($anotherMatrix);
$matrix->mSubtract($anotherMatrix);
$matrix->mMultiply($anotherMatrix);
$matrix->mMultiplyByScalar($scalarIntOrFloat);
$matrix->mChangeSign();

// Matrix unary operations
$transpose = $matrix->transpose();
$trace = $matrix->trace();
$determinant = $matrix->determinant();
$rowEchelonForm = $matrix->ref();
$reducedRowEchelonForm = $matrix->rref();

// Matrix unary operations (mutating methods)
$matrix->mTranspose();
$matrix->mRef();             //Row echelon form
$matrix->mRref();            //Reduced row echelon form

// Matrix resizing and concatenation
$joinRight = $matrix->joinRight($anotherMatrix);
$joinBottom = $matrix->joinBottom($anotherMatrix);

// Matrix resizing and concatenation (mutating methods)
$matrix->mJoinRight($anotherMatrix);
$matrix->mJoinBottom($anotherMatrix);

 // Create a 1x2 submatrix starting from the element at row 0, column 0 till the element at row 1, column 2 
$submatrix = $matrix->submatrix(0, 0, 1, 2);

// Convert a matrix row or column to a Vector object
$rowVector = $matrix->rowToVector(1);
$columnVector = $matrix->columnToVector(2);

// Conversion to a string representation
$string = $matrix->toString();
$string = (string) $matrix;
// Both ways will return
// [1, 2, 3]
// [4, 5, 6]
// [7, 8, 9]

向量

Vector类扩展了Matrix类，因此所有Matrix方法也都可用。其中一些方法有额外的包装，以便更方便地使用，例如fill()与vectorFill()。

// Create a new vector using the class constructor
$rowVector = new Vector([[1, 2, 3]]);
$columnVector = new Vector([
    [1],
    [2],
    [3],
]);

// Or use a suitable factory method
$vector = Vector::fromArray([1, 2, 3], VectorEnum::Column);   // Creates a [[1], [2], [3]] column vector
$vector = Vector::vectorFill(5, 1.1, VectorEnum::Row);         // Creates a [[1.1, 1.1, 1.1, 1.1, 1.1]] row vector
$vector = Vector::vectorRandom(5, -3.5, 9.5)   // Make a with 5-component vector filled with random float numbers between -3.5 and 9.5
$vector = Vector::randomInt(3, 1, 10)    // Make a 3-component vector filled with random integer numbers between 1 and 10

// Get the vector type (orientation)
$rowVector->vectorType();                 // Returns VectorEnum::Row
$columnVector->vectorType();              // Returns VectorEnum::Column

// Vector size
$numberOfComponents = $rowVector->size(); // Returns 3
$numberOfElements = count($rowVector);    // Alternative way as Vector implements "Countable" interface
$rows = $rowVector->rows();               // Returns 1
$columns = $rowVector->columns();         // Returns 3
$rows = $columnVector->rows();               // Returns 3
$columns = $columnVector->columns();         // Returns 1  

// Element getters and setters (zero-based indexing)
$element = $rowVector->vGet(2);            // Equivalent to get(1, 2) using the Matrix method
$rowVector->vSet(2, -15.6);                // Equivalent to set(1, 2, -15.6) using the Matrix method
$doesElementExist = $rowVector->vIsSet(2); // Equivalent to isSet(2) using the Matrix method 

// Alternative getters and setters via "ArrayAccess" interface
$element = $rowVector[2];    // Equivalent to $rowVector->vGet(2)
$rowVector[2] = 15;          // Equivalent to $rowVector->vSet(2, 15) 
$doesElementExist = isset($rowVector[2]);

// Get vector as an array
$columnVector->toArray();
/* Returns the 2D column array:
 * [
 *  [1],
 *  [2],
 *  [3],
 * ]
 */
$columnVector->toPlainArray();      // Returns a 1D array [1, 2, 3]

// Get a subvector
$subvector = $rowVector->subvector(1, 2); // Returns a new vector [2, 3]

// Vector binary operations
dotProduct = $rowVector->dotProduct($anotherVector);
$crossProduct = $rowVector->crossProduct($anotherVector);

// Conversion to a string representation
$string = $rowVector->toString();
$string = (string) $rowVector;
// Both ways will return
// [1, 2, 3]
$string = $columnVector->toString();
$string = (string) $columnVector;
// Both ways will return
// [1]
// [2]
// [3]

数字

有理数

一个用于存储有理数并在其上进行数学运算的类

// Create a new rational number using class constructor Rational($whole, $numerator, $denominator)
$r = new Rational(5, 1, 2);             // Creates a rational number 1 1/2

// Or use a suitable class constructor
$r = Rational::fromString("-5 1/3");    // Equivalent to "new Rational(-5, -1, 3)"
$r = Rational::fromInt(15);             // Equivalent to "new Rational(15, 0, 1)"
$r = Rational::fromFloat(0.333333);     // Equivalent to "new Rational(0, 1, 3)"

// Convert a rational to a float
$r = Rational::fromString("1/3");
$float = $r->toFloat();                 // Returns 0.33333333333

// Convert a rational to a text form using toString() method
$string = $r->toString();               // Returns "-5 1/3"
// or string cast
$string = (string) $r;  

// Compare a rational number with zero
$isZero = $r->isZero();
// Or with another rational
$isEqual = $r->isEqual($anotherRational);

// Check if the rational number is negative
$isNegative = $r->isNegative();
// Or if it is positive
$isPositive = $r->isPositive();

// Check if the rational number is an integer
$isInteger = $r->isInteger();

// Calculate the reciprocal (multiplicative inverse)
$reciprocal = $r->reciprocal();

// Arithmetics with rationals
$r1 = Rational::fromString("2 3/8");
$r2 = Rational::fromString("4 9/17");
$sum = $r1->add($r2);
$difference = $r1->subtract($r2);
$multiplication = $r1->multiply($r2);
$division = $r1->divide($r2);