MKDOC files.

README.md

@@ -15,71 +15,131 @@
   <img src="https://i.imgur.com/QoIbhqj.png" width="70%" />
 </p>
 
+# 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:
 ```
 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.
+