+
+# Efficient PHP library for data scientists
-PHPSci is a PHP Library for scientific computing powered by C. You **must** compile and install
-[phpsci-ext](https://www.github.com/phpsci/phpsci-ext).
+PHPSci is a PHP Library for scientific computing powered by C.
+You **must** compile and install
+[PHPSci CArray Extension](https://www.github.com/phpsci/phpsci-ext).
+
+
+It enables scientific operations in PHP to be performed up to 800
+times faster than current implementations.
-`
-We will soon provide precompiled!
-`
## Installation
You can install PHPSci using composer:
@@ -29,57 +32,114 @@ You can install PHPSci using composer:
composer require phpsci/phpsci:dev-master
```
+> **ATTENTION:** You must install PHPSci extension, otherwise it won't work.
## Getting Started
-You can create an CArray using the `fromArray` static method:
-
-```php
-$autoloader = require_once dirname(__DIR__) . '/vendor/autoload.php';
+PHPSci arrays are different from PHP arrays, they are called CArrays and work in a peculiar way. Let's look at the
+result of the `print_r` function in a PHP array and a twin CArray.
-use PHPSci\PHPSci as psci;
-$matrix = psci::fromArray([[2 , 4], [6 , 9]]);
-echo $matrix;
+### PHP Array
+```php
+$a = [[1,2],[3,4]];
+print_r($a);
```
-
```php
-[
- [ 2 4 ]
- [ 6 9 ]
-]
+Array
+(
+ [0] => Array
+ (
+ [0] => 1
+ [1] => 2
+ )
+
+ [1] => Array
+ (
+ [0] => 3
+ [1] => 4
+ )
+
+)
```
-Let's transpose our recently created Matrix:
+### PHPSci CArray
```php
-echo psci::transpose($matrix);
+$a = PHPSci::fromArray([[1,2],[3,4]]);
+print_r($a);
```
```php
-[
- [ 2 6 ]
- [ 4 9 ]
-]
+PHPSci\PHPSci Object
+(
+ [internal_pointer:protected] => PHPSci\Kernel\Orchestrator\MemoryPointer Object
+ (
+ [uuid:protected] => 1
+ [x:protected] => 2
+ [y:protected] => 2
+ [carray_internal:protected] => CArray Object
+ (
+ [uuid] => 1
+ [x] => 2
+ [y] => 2
+ )
+
+ )
+
+)
```
+This happens because `print_r` only works with PHP's natural functions, objects, and arrays,
+which is not the case for a CArray.
+An array of PHPSci is just a pointer to memory. It carries with it the position of memory
+where its data has been allocated.
+
+
+The `MemoryPointer` object is a mirror of the `CArray` object, it carries with it the information
+needed to communicate with the C backend.
+
-## How it works?
+To view your data, you can use the `echo` method or transform your CArray into a PHP array.
-PHPSci is powered by **CArrays**. To understand more about how it works, read [PHPSci CArrays](https://www.github.com/phpsci/phpsci-ext)
-and it [documentation](http://phpsci-carray.readthedocs.io).
+## Data Visualization
+There are two ways to view your data in an PHPSci array:
-### Inside CArrays
-A `print_r` look at a CArray
+### Using echo
```php
-PHPSci\PHPSci Object
+$a = PHPSci::fromArray([[1,2],[3,4]]);
+echo $a;
+```
+```php
+[
+ [ 1.000000 2.000000 ]
+ [ 3.000000 4.000000 ]
+]
+```
+### Transforming into a PHP array
+```php
+$a = PHPSci::fromArray([[1,2],[3,4]]);
+print_r($a->toArray());
+```
+```php
+Array
(
- [internal_pointer:protected] => PHPSci\Kernel\Orchestrator\MemoryPointer Object
+ [0] => Array
(
- [uuid:protected] => 1
- [rows:protected] => 2
- [cols:protected] => 2
+ [0] => 1
+ [1] => 2
+ )
+
+ [1] => Array
+ (
+ [0] => 3
+ [1] => 4
)
)
```
-Everything inside `MemoryPointer Object` is generated by C code. Use `echo` to see your matrix instead
-of `print_r` as PHPSci don't use PHP Arrays.
+
+Try to perform all the necessary calculations
+before turning your PHPSci array into a PHP array.
+
+The `echo` command is considerably more efficient than the `toArray`
+command. Try to use the toArray only when you want to use the results in a natively PHP function.
+
diff --git a/docs/array_initializers.md b/docs/array_initializers.md
new file mode 100644
index 0000000..f8a34c9
--- /dev/null
+++ b/docs/array_initializers.md
@@ -0,0 +1,275 @@
+# Creating PHPSci arrays
+Useful methods for initializing / creating arrays.
+
+- [Ones and Zeros](#Ones and Zeros)
+ - [zeros](#zeros) - Return PHPSci Array full of zeros
+ - [identity](#identity) - Return the identity PHPSci array
+- [Ranges](#Ranges)
+ - [arange](#arange) - Return evenly spaced values within a given interval.
+ - [logspace](#logspace) - Return numbers spaced evenly on a log scale.
+ - [linspace](#linspace) - Return evenly spaced numbers over a specified interval.
+- [PHP native data](#PHP native data)
+ - [fromArray](#fromarray) - Return PHPSci Array from input array
+ - [toArray](#toarray) - Return array from input PHPSci array
+---
+
+## Ones and Zeros
+
+### zeros
+```php
+public static function zeros(array $shape);
+```
+Return PHPSci Array full of zeros.
+
+##### Parameters
+- `array` **$shape** - Shape of new array.
+
+##### Returns
+- `PHPSci array` - CArray of given shape.
+
+##### Example
+```php
+use PHPSci\PHPSci as ps;
+
+echo ps::zeros([2,2]);
+```
+```php
+[
+ [ 0.000000 0.000000 ]
+ [ 0.000000 0.000000 ]
+]
+```
+```php
+use PHPSci\PHPSci as ps;
+
+echo ps::zeros([2,]);
+```
+```php
+[ 0.000000 0.000000 ]
+```
+
+---
+
+### identity
+```php
+public static function identity(int $n);
+```
+Return the identity PHPSci array.
+
+##### Parameters
+- `array` **$n** - Size of identity matrix (n,n)
+
+##### Returns
+- `PHPSci array` - Identity CArray of given size.
+
+##### Example
+```php
+use PHPSci\PHPSci as ps;
+
+echo ps::identity(5);
+```
+```php
+[
+ [ 1.000000 0.000000 0.000000 0.000000 0.000000 ]
+ [ 0.000000 1.000000 0.000000 0.000000 0.000000 ]
+ [ 0.000000 0.000000 1.000000 0.000000 0.000000 ]
+ [ 0.000000 0.000000 0.000000 1.000000 0.000000 ]
+ [ 0.000000 0.000000 0.000000 0.000000 1.000000 ]
+]
+```
+
+---
+
+## Ranges
+
+### arange
+```php
+public static function arange(double $stop, double $start, double $step);
+```
+Return evenly spaced values within a given interval.
+
+##### Parameters
+- `number` **$stop** - End of interval. The interval does not include this value.
+- `number` **$start** *Optional* - Start of interval. The interval includes this value. Defaults to 0.
+- `number` **$step** *Optional* - Spacing between values. Defaults to 1.
+
+##### Returns
+- `PHPSci` - PHPSci with array of evenly spaced values.
+
+##### Example
+```php
+use PHPSci\PHPSci as ps;
+
+
+$a = ps::arange(3);
+echo $a;
+```
+```php
+[ 0.000000 1.000000 2.000000 ]
+```
+```php
+use PHPSci\PHPSci as ps;
+
+
+$a = ps::arange(3,1,0.5);
+echo $a;
+```
+```php
+[ 1.000000 1.500000 2.000000 2.500000 ]
+```
+
+---
+
+### linspace
+```php
+public static function linspace(float $start, float $stop, int $num);
+```
+Return evenly spaced numbers over a specified interval.
+
+##### Parameters
+- `number` **$start** - The starting value of the sequence.
+- `number` **$stop** - The end value of the sequence.
+- `int` **$num** *Optional* - Number of samples to generate. Default is 50.
+
+##### Returns
+- `PHPSci` - PHPSci with array of equally spaced samples in the closed interval.
+
+##### Example
+```php
+use PHPSci\PHPSci as ps;
+
+
+$a = ps::linspace(1,5);
+echo $a;
+```
+```php
+[ 1.000000 1.020408 1.040816 1.061224 1.081633 1.102041 1.122449 1.142857 1.163265 1.183674 1.204082 1.224490 1.244898 1.265306 1.285714 1.306122 1.326531 1.346939 1.367347 1.387755 1.408163 1.428571 1.448980 1.469388 1.489796 1.510204 1.530612 1.551020 1.571429 1.591837 1.612245 1.632653 1.653061 1.673469 1.693877 1.714286 1.734694 1.755102 1.775510 1.795918 1.816326 1.836735 1.857143 1.877551 1.897959 1.918367 1.938776 1.959184 1.979592 2.000000 ]
+```
+```php
+use PHPSci\PHPSci as ps;
+
+
+$a = ps::linspace(1,5,5);
+echo $a;
+```
+```php
+[ 1.000000 1.250000 1.500000 1.750000 2.000000 ]
+```
+
+---
+
+### logspace
+```php
+public static function logspace(float $start, float $stop, int $num, float $base);
+```
+Return numbers spaced evenly on a log scale.
+
+##### Parameters
+- `number` **$start** - ``$base ** $start`` is the starting value of the sequence.
+- `number` **$stop** - ``$base ** $stop`` is the final value of the sequence.
+- `int` **$num** *Optional* - Number of samples to generate. Default is 50.
+- `number` **$base** *Optional* - The base of the log space.
+
+##### Returns
+- `PHPSci` - PHPSci with array of equally spaced on a log scale.
+
+##### Example
+```php
+use PHPSci\PHPSci as ps;
+
+
+$a = ps::logspace(1, 2);
+echo $a;
+```
+```php
+[ 10.000000 10.481132 10.985411 11.513953 12.067925 12.648551 13.257112 13.894953 14.563486 15.264181 15.998588 16.768330 17.575106 18.420700 19.306976 20.235895 21.209507 22.229963 23.299522 24.420534 25.595482 26.826960 28.117689 29.470518 30.888435 32.374577 33.932217 35.564800 37.275936 39.069397 40.949146 42.919338 44.984318 47.148655 49.417122 51.794735 54.286755 56.898659 59.636230 62.505516 65.512848 68.664879 71.968582 75.431213 79.060440 82.864288 86.851143 91.029823 95.409554 100.000000 ]
+```
+```php
+use PHPSci\PHPSci as ps;
+
+
+$a = ps::logspace(1, 2, 5);
+echo $a;
+```
+```php
+[ 10.000000 17.782795 31.622776 56.234131 100.000000 ]
+```
+```php
+use PHPSci\PHPSci as ps;
+
+
+$a = ps::logspace(1, 2, 5, 5);
+echo $a;
+```
+```php
+[ 5.000000 7.476744 11.180340 16.718508 25.000000 ]
+```
+---
+
+## PHP native data
+
+### fromArray
+```php
+public static function fromArray(array $array);
+```
+Return PHPSci Array from PHP array.
+
+##### Parameters
+- `array` **$array** - PHP Array to be converted.
+
+##### Returns
+- `PHPSci` - PHPSci with array of with same shape and values of `$array`
+
+##### Example
+```php
+$a = ps::fromArray([[1, 2],[3, 4]]);
+echo $a;
+```
+```php
+[
+ [ 1.000000 2.000000 ]
+ [ 3.000000 4.000000 ]
+]
+```
+
+---
+
+### toArray
+```php
+public function toArray();
+```
+Return a PHP array from PHPSci object.
+
+##### Returns
+- `array` - Array of with same shape and values of PHPSci array.
+
+##### Example
+```php
+use PHPSci\PHPSci as ps;
+
+
+$a = ps::fromArray([[1, 2],[3, 4]]);
+print_r($a->toArray());
+```
+```php
+Array
+(
+ [0] => Array
+ (
+ [0] => 1
+ [1] => 2
+ )
+
+ [1] => Array
+ (
+ [0] => 3
+ [1] => 4
+ )
+
+)
+```
+
+
+
+
+
diff --git a/docs/array_manipulation.md b/docs/array_manipulation.md
new file mode 100644
index 0000000..e69de29
diff --git a/docs/carray.md b/docs/carray.md
new file mode 100644
index 0000000..e69de29
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..1fc2760
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,131 @@
+
+
+