flex-cartesian 1.3.0 → 2.0.0.beta

data/README.md

@@ -1,530 +1,224 @@
-# FlexCartesian
+<h1 align="center">FlexCartesian</h1>
+<p align="center">
+  <b>Model real systems as functions of parameters.<br>Extract behavioural blueprints.<br>Get insights with a few lines of code.</b>
+</p>
 
-**Ruby implementation of flexible and human-friendly operations on Cartesian products**  
-
-## Features
-
-✅ Named dimensions with arbitrary keys
-
-✅ Enumerate over Cartesian space with a single block argument  
-
-✅ Actions on Cartesian are decoupled from dimensionality: `s.cartesian { |v| do_something(v) }`
-
-✅ Conditions for Cartesian space: `s.cond(:set) { |v| v.dim1 > v.dim2 } }`
-
-✅ Calculation over named dimensions: `s.cartesian { |v| puts "#{v.dim1} and #{v.dim2}" }`
+---
 
-✅ Functions on Cartesian space: `s.func(:add, :my_sum) { |v| v.dim1 + v.dim2 }`
+# What Is It
 
-✅ Lazy and eager evaluation
+FlexCartesian is a novel approach to parameter space analysis. It introduces the Parametric Behaviour Blueprinting paradigm, abbreviated as PBB.
 
-✅ Progress bars for large Cartesian spaces
+# What Is It For
 
-✅ Export of Cartesian space to Markdown or CSV
+Most systems around us are functions of parameters.<br/>
 
-✅ Import of Cartesian space from JSON or YAML
+The LLM you use has inference parameters, and its functions are response quality, response time, and throughput. The cloud storage you use has configuration parameters, and its functions are IOPS and throughput. Even the car you drive has driving parameters, and its function is cost per mile.
 
-✅ Export of Cartesian space to Markdown or CSV
+As a rule, a parametric system's behavior is characterized by its function. Naturally, you want to tune those parameters to bring the system to its absolute best operating mode: the lowest cost per mile, the highest storage IOPS, or the lowest response time from an LLM. This leads to two fundamental questions:
 
-✅ Structured and colorized terminal output  
+<p align="center">
+<b>HOW DO PARAMETERS INFLUENCE THE BEHAVIOUR OF THE SYSTEM?</b>
+</p>
 
-## Use Cases
+<p align="center">
+<b>WHAT IS THE ABSOLUTE BEST OPERATING MODE OF THE SYSTEM?</b>
+</p>
 
-`FlexCartesian` is especially useful in the following scenarios.
+FlexCartesian addresses both questions. It explores the behavior of your system and identifies its optimal operating modes.
 
-### 1. Sweep Analysis of Performance
+# Why It Exists
 
-Systematically evaluate an application or algorithm across all combinations of parameters:
+FlexCartesian fills several practical gaps left by conventional benchmarking and parameter space analysis tools.
 
-- Parameters: `threads`, `batch_size`, `backend`, etc
-- Metrics: `throughput`, `latency`, `memory`
-- Output: CSV or Markdown tables
+**> _Data gathering is separated from data analysis._**
 
-### 2. Hyperparameter Tuning for ML Models
+Specifically, benchmarking tools blindly provide raw data, while modeling tools blindly assume that data has already been prepared somehow.
+There is a need for a single tool that builds a model of a system and probes live data from it in a structured, consistent way that perfectly aligns with that model.
 
-Iterate over all combinations of hyperparameters:
+**> _Data gathered from systems is often scattered, inconsistent, unstructured, and incomplete._**
 
-- Examples: `learning_rate`, `max_depth`, `subsample`, `n_estimators`
-- With constraints (e.g., `max_depth < 10 if learning_rate > 0.1`)
-- With computed evaluation metrics like `accuracy`, `AUC`, etc
+What's even worse, you rarely know in advance if there are gaps in the fetched data or where they might be.
+There is a need for a tool that establishes a rigorous mathematical model of the system first, and then gathers data exactly as the model requires to represent the system consistently.
 
-### 3. Infrastructure and System Configuration
+**> _System analysis is spread across System Engineer, System Architect, and Data Scientist roles._**
 
-Generate all valid infrastructure configurations:
+The first role knows how to benchmark and gather data. The second role understands the system's architecture. The third knows how to explore the data. There is a need for a simple tool that enables any of these roles to conduct full-cycle analysis without delays. For example, a System Architect should be able to iteratively run an analysis, updating the data in the model quickly and independently.
 
-```ruby
-region:   ["us-west", "eu-central"]
-tier:     ["basic", "pro"]
-replicas: [1, 3, 5]
-```
+**> _Heavy-weight scripting is required to turn specialized libraries into end-user tools._**
 
-With conditions like "basic tier cannot have more than one replica:
-```ruby
-s.cond(:set) { |v| (v.tier == "basic" ? v.replicas == 1 : true) }
-```
+There is a need for a high-level, concise Domain-Specific Language (DSL) to gather data, explore it, and model the parametric system.
 
-### 4. Mass Testing of CLI Commands
-Generate and benchmark all valid CLI calls:
+# Essential Advantages
 
-```bash
-myapp --threads=4 --batch=32 --backend=torch
-```
+FlexCartesian elevates the traditional parameter space analysis paradigm to the next level, which we call **Parametric Behaviour Blueprinting (PBB)**.
 
-Capture runtime, output, errors, etc.
+Conventional parameter space analysis takes the existence of parameter values and system states for granted, focusing solely on exploring the state (sensitivity, robustness, trade-offs, extrema, heatmaps, etc.). PBB extends this scope further:
 
-### 5. Input Generation for UI/API Testing
-Automatically cover input parameter spaces for:
+**1. Live data gathering.** FlexCartesian fetches data directly from a real system (digital or physical) using defined `behavioural functions`.
 
-- HTTP methods: ["GET", "POST"]
-- User roles: ["guest", "user", "admin"]
-- Language settings: ["en", "fr", "de"]
+**2. Evolving blueprints.** A live linkage to the real system maintains a behavioural blueprint that evolves over time. This is driven by `data sources` feeding the behavioural functions, natively supporting the temporal dimension in the model.
 
-### 6. Scientific and Engineering Simulations
-Generate multidimensional experimental spaces for:
+**3. Structured Consistency.** FlexCartesian maintains the data gathered from the real system in a structured, complete order. This is enforced by FlexCartesian's core mathematical model: `parameter space` + `conditions` + `behavioural functions`. These three concepts guarantee that the system's behavior is described correctly for any valid combination of parameters.
 
-- Physics simulations
-- Bioinformatics parameter sweeps
-- Network behavior modeling, etc
+**4. Reverse Linkage for Simulation.** FlexCartesian doesn't just use the live linkage to gather data; it allows you to use the blueprint as a substitute for the real system. This unlocks new opportunities in system modeling, testing, and integration. It is particularly useful for air-gapped systems or AI training, where providing real system data is unavailable or prohibitively expensive.
 
-### 7. Structured Reporting and Visualization
-Output Cartesian data as:
+Additionally, FlexCartesian implements PBB via a highly expressive Ruby-based DSL. This allows you to execute powerful concepts in just a single line of code, natively integrating all the flexibility and elegance of Ruby.  
 
-- Markdown (for GitHub rendering)
-- CSV (for Excel, Google Sheets, and more advanced BI tools)
-- Plain text (for CLI previews)
+## Example #1: Avoiding semantic shift in ChatGPT
 
-### 8. Test Case Generation
-Use it to drive automated test inputs for:
+Suppose we want to find the optimal operating mode for ChatGPT—specifically, the ranges of `temperature` and `tokens` where the model gives stable, consistent answers to repeated questions. A lack of stability is known as _semantic shift,_ which is crucial to avoid in fields like law or science, where an AI assistant must provide reliable answers based on a strict corpus of documents.
 
-- RSpec shared examples
-- Minitest table-driven tests
-- PyTest parameterization
+Perhaps, we want to find optimal operating mode of ChatGPT - specifically, the ranges of its temperature and tokens where ChatGPT gives stable and consistent answers to repeated question. The lack of such stability is called semantic shift, which is crucial to avoid in such fields as law or science, where AI assistant must provide very stable answers based on a given corpus of documents.
 
-## Installation
+While you can run [this example](https://github.com/Yuri-Rassokhin/flex-cartesian/tree/main/examples/13_chatgpt_semantic_shift) yourself, here's how FlexCartesian determines a semantic-shift-free operating mode, step by step.
 
-```bash
-bundle install
-gem build flex-cartesian.gemspec
-gem install flex-cartesian-*.gem
-```
-
-
-
-## Usage
+Enable FlexCartesian:
 
 ```ruby
-#!/usr/bin/ruby
-
 require 'flex-cartesian'
-
-
-
-# BASIC CONCEPTS
-
-# 1. Cartesian object is a set of combinations of values of dimansions.
-# 2. Dimensions always have names.
-
-puts "\nDefine named dimensions"
-example = {
-  dim1: [1, 2],
-  dim2: ['x', 'y'],
-  dim3: [true, false]
-}
-
-puts "\nCreate Cartesian space"
-s = FlexCartesian.new(example)
-
-def do_something(v)
-  # do something here on vector v and its components 
-end
-
-
-
-# ITERATION OVER CARTESIAN SPACE
-
-# 3. Iterator is dimensionality-agnostic, that is, has a vector syntax that hides dimensions under the hood.
-#    This keeps foundational code intact, and isolates modifications in the iterator body 'do_something'.
-# 4. For efficiency on VERY largse Cartesian spaces, there are
-#    a). lazy evaluation of each combination
-#    b). progress bar to track time-consuming calculations.
-
-puts "\nIterate over all Cartesian combinations and execute action (dimensionality-agnostic style)"
-s.cartesian { |v| do_something(v) }
-
-puts "\nIterate over all Cartesian combinations and execute action (dimensionality-aware style)"
-s.cartesian { |v| puts "#{v.dim1} & #{v.dim2}" if v.dim3 }
-
-puts "\nIterate and display progress bar (useful for large Cartesian spaces)"
-s.progress_each { |v| do_something(v) }
-
-puts "\nIterate in lLazy mode, without materializing entire Cartesian product in memory"
-s.cartesian(lazy: true).take(2).each { |v| do_something(v) }
-
-
-
-# FUNCTIONS ON CARTESIAN SPACE
-
-# 5. A function is a virtual dimension that is calculated based on a vector of base dimensions.
-#    You can think of a function as a scalar field defined on Cartesian space.
-# 6. Functions are printed as virtual dimensions in `.output`.
-# 7. Functions do not add to `.size` of Cartesian space.
-
-puts "\nAdd function 'triple'"
-puts "Note: function is visualized in .output as a new dimension"
-s.func(:add, :triple) { |v| v.dim1 * 3 + (v.dim3 ? 1: 0) }
-s.func(:run)
-s.output
-
-puts "\Add and then remove function 'test'"
-s.func(:add, :test) { |v| v.dim3.to_i }
-s.func(:del, :test)
-
-puts "\nThis function will calculate first, always"
-s.func(:add, :test_first, order: :first) { puts "HERE" }
-
-puts "\nThis function will calculate last, always"
-s.func(:add, :test_last, order: :last) { puts "HERE" }
-
-puts "\nNew functions respect first and last ones"
-s.func(:add, :test_more) { puts "HERE" }
-
-puts "\nFirst and last functions are handy for pre- and post-processing for each combination"
-
-# CONDITIONS ON CARTESIAN SPACE
-
-# 8. A condition is a logical constraint for allowed combitnations of Cartesian space.
-# 9. Using conditions, you can take a slice of Cartesian space.
-#    In particular, you can reflect semantical dependency of dimensional values.
-
-puts "Build Cartesian space that includes only odd values of 'dim1' dimension"
-s.cond(:set) { |v| v.dim1.odd? }
-puts "print all the conditions in format 'index | condition '"
-s.cond
-puts "Test the condition: print the updated Cartesian space"
-s.output
-puts "Test the condition: check the updated size of Cartesian space"
-puts "New size: #{s.size}"
-puts "Clear condition #0"
-s.cond(:unset, index: 0)
-puts "Clear all conditions"
-s.cond(:clear)
-puts "Restored size without conditions: #{s.size}"
-
-
-
-# PRINT
-
-puts "\nPrint Cartesian space as plain table, all functions included"
-s.output
-puts "\nPrint Cartesian space as Markdown"
-s.output(format: :markdown)
-puts "\nPrint Cartesian space as CSV"
-s.output(format: :csv)
-puts "\nGranular output of Cartesian space dimensions: #{s.dimensions(values: false)}"
-puts "\nGranular output of Cartesian vectors:"
-s.cartesian { |v| puts s.dimensions(v, separator: ' ') }
-
-
-
-# IMPORT / EXPORT
-
-puts "\nImport Cartesian space from JSON (similar method for YAML)"
-File.write('example.json', JSON.pretty_generate(example))
-puts "\nNote: after import, all assigned functions will calculate again, and they appear in the output"
-s.import('example.json').output
-puts "\nExport Cartesian space to YAML (similar method for JSON)"
-s.export('example.yaml', format: :yaml)
-
-
-
-# UTILITIES
-
-puts "\nGet number of Cartesian combinations"
-puts "Note: .size counts only dimensions, it ignores virtual constructs (functions, conditions, etc.)"
-puts "Total size of Cartesian space: #{s.size}"
-puts "\nPartially converting Cartesian space to array:"
-array = s.to_a(limit: 3)
-puts array.inspect
 ```
 
-## Example
-
-The most common use case for FlexCartesian is sweep analysis, that is, analysis of target value on all possible combinations of its parameters.
-FlexCartesian has been designed to provide a concise form for sweep analysis:
+Define the parameter space:
 
 ```ruby
-require 'flex-cartesian'
-
-# create Cartesian space from JSON describing input parameters
-s = FlexCartesian.new(path: './config.json')
-
-# Define the values we want to calculate on all possible combinations of parameters
-s.func(:add, :cmd) { |v| v.threads * v.batch }
-s.func(:add, :performance) { |v| v.cmd / 3 }
-
-# Calculate
-s.func(:run)
-
-# Save result as CSV, to easily open it in any business analytics tool
-s.output(format: :csv, file: './benchmark.csv')
-# For convenience, print result to the terminal
-s.output
-```
-
-As this code is a little artificial, let us build real-world example.
-Perhaps, we want to analyze PING perfomance from our machine to several DNS providers: Google DNS, CloudFlare DNS, and Cisco DNS.
-For each of those services, we would like to know:
-
-- What is our ping time?
-- How does ping scale by packet size?
-- How does ping statistics vary based on count of pings?
-
-These input parameters form the following dimensions.
-
-```json
-{
-  "count": [2, 4],
-  "size": [32, 64],
-  "target": [
-    "8.8.8.8",           // Google DNS
-    "1.1.1.1",           // Cloudflare DNS
-    "208.67.222.222"     // Cisco OpenDNS
-  ]
-}
+space = FlexCartesian.new({
+		temperature: [0.0, 0.2, 0.4, 0.6, 0.8, 1.0],
+		tokens: [20, 50, 100, 200, 400]})
 ```
 
-Note that `//` isn't officially supported by JSON, and you may want to remove the comments if you experience parser errors.
-Let us build the code to run over these parameters.
+Define the behavioural function `response`. For any combination of parameters, it returns the response given by ChatGPT to the same test question:
 
 ```ruby
-require 'flex-cartesian'
+msg = [ { role: "system", content: "You are a precise and consistent assistant." },
+        { role: "user", content: "Explain quantum mechanics in one sentence." } ]
 
-s = FlexCartesian.new(path: './ping_parameters.json') # file with the parameters as given above
-
-result = {} # raw result of each ping
-
-s.func(:add, :command) { |v| "ping -c #{v.count} -s #{v.size} #{v.target}" } # ping command
-s.func(:add, :raw_ping, hide: true) { |v| result[v.command] ||= `#{v.command} 2>&1` } # capturing ping result
-s.func(:add, :time) { |v| v.raw_ping[/min\/avg\/max\/(?:mdev|stddev) = [^\/]+\/([^\/]+)/, 1]&.to_f } # fetch ping time from result
-s.func(:add, :min) { |v| v.raw_ping[/min\/avg\/max\/(?:mdev|stddev) = ([^\/]+)/, 1]&.to_f } # fetch min time from result
-s.func(:add, :loss) { |v| v.raw_ping[/(\d+(?:\.\d+)?)% packet loss/, 1]&.to_f } # fetch ping loss from result
-
-s.func(:run, progress: true, title: "Pinging") # Sweep analysis! Benchmark all possible combinations of parameters
-
-s.output(format: :csv, file: './result.csv') # save benchmark result as CSV
-
-s.output(colorize: true) # for convenience, show result in terminal
+space.func(:add, :response) { |v| llm(temperature: v.temperature, max_tokens: v.tokens, messages: msg ) }
 ```
 
-If you run the code, after a while it will generate benchmark results on the screen:
+Enrich the system with two additional behavioural functions. For any answer provided by `response`, the `embedding` function returns its vector embedding. The `semantic_shift` function then calculates how far the response drifts away from the very first answer ("anchor") given by the model. This value is exactly what we need!
 
-![Ping Benchmark Example](doc/ping_benchmark_example.png)
+```ruby
+space.func(:add, :embedding) { |v| anchor ||= embed(v.response); embed(v.response) }
+space.func(:add, :semantic_shift) { |v| (1.0 - cosine(v.embedding, anchor)).round(2) }
+```
 
-Additionally, CSV version of this result is saved as `./benchmark.csv`
+Next, we compute all the functions across the entire parameter space.
+Behind the scenes, FlexCartesian iterates each function over all possible parameter combinations.
 
-The PING benchmarking code above is 100% practical and illustrative.
-You can modify it and benchmark virtually anything:
+```ruby
+space.func(:run, progress: true)
+```
 
-- Local block devices using `dd`
-- GPU-to-Storage connection using `gdsio`
-- Local file systems using FS-based utilities
-- Local CPU RAM using RAM disk or specialized benchmarks for CPU RAM
-- Database performance using SQL client or non-SQL client utilities
-- Performance of object storage of cloud providers, be it AWS S3, OCI Object Storage, or anything else
-- Performance of any AI model, from simplistic YOLO to heavy-weight LLM such as LLAMA, Cohere, or DeepSeek
-- ... Any other target application or service
+Upon completion, FlexCartesian holds the Parametric Behaviour Blueprint of our system.
+Now, we can visualize this PBB as a 2D heatmap showing how the semantics of ChatGPT's answers depend on `tokens` and `temperature`
 
-In any use case, FlexCartesian will unfold complete landscape of the target performance over all configurable parameters.
-As result, you will be able to spot optimal configurations, correlations, bottlenecks, and sweet spots.
-Moreover, you will make your conclusions in a justifiable way.
+```ruby
+space.visualize(x: :temperature, y: :tokens, func: :semantic_shift, output: "./viz.html")
+```
 
-Here is example of using FlexCartesian for [performance/cost analysis of YOLO](https://www.linkedin.com/pulse/comparing-gpu-a10-ampere-a1-shapes-object-oci-yuri-rassokhin-rseqf).
+When we open `./viz.html` in a browser, we see the semantic shift varying from `0.0` (identical to the first answer) to `1.0` (totally inconsistent):
 
+<p align="center">
+	<img src="docs/assets/viz/example-low-rate.gif" width="600"/>
+</p>
 
+The heatmap gives us our answer: to completely avoid semantic shift, we should keep the temperature at or below `0.2`.
+The number of tokens has no measurable influence on response stability.
+Notably, even at temperatures beyond `0.2`, the responses remain respectably consistent, with the shift barely reaching `0.2`.
 
-## API Overview
+Finally, we want to mathematically assess the influence of each parameter:
 
-### Initialization
 ```ruby
-FlexCartesian.new(dimensions = nil, path: nil, format: :json)
+space.analyzer(:morris, trajectories: 10, step: 0.1, seed: 42).output(func: :semantic_shift, format: :markdown)
 ```
-- `dimensions_hash`: optional hash with named dimensions; each value can be an `Enumerable` (arrays, ranges, etc)
-- `path`: optional path to file with stored dimensions, JSON and YAML supported
-- `format`: optional format of `path` file, defaults to JSON
 
-Example:
-```ruby
-dimensions = {
-  dim1: [1, 2],
-  dim2: ['x', 'y'],
-  dim3: [true, false]
-}
+This produces a Markdown table quantifying the influence of the parameters:
 
-FlexCartesian.new(dimensions)
-```
+|parameter  |influence[semantic_shift]|deviation|probes|category|linearity        |recommendation                                                                                   |
+|-----------|-------------------------|---------|------|--------|-----------------|-------------------------------------------------------------------------------------------------|
+|tokens     |0.14                     |0.22     |10    |strong  |highly non-linear|critical parameter with complex interactions; prioritize for variance-based analysis (e.g. Sobol)|
+|temperature|0.09                     |0.19     |10    |strong  |highly non-linear|critical parameter with complex interactions; prioritize for variance-based analysis (e.g. Sobol)|
 
----
+This sensitivity table confirms the strong influence of both parameters and, most importantly, categorizes their influence as highly non-linear. This means we cannot make decisions based on just a few isolated probes. Instead, we must build a complete behavioural blueprint across the entire parameter space and find the "sweet spot": temperature <= 0.2, regardless of tokens.
 
-### Iterate Over All Combinations
+## Example #2: Sensitivity of AWS DynamoDB servers
 
-Example:
-```ruby
-# With block
-cartesian(dims = nil, lazy: false) { |vector| ... }
-# Without block: returns Enumerator
-cartesian(dims = nil, lazy: false)
-```
-- `dims`: optional dimensions hash (default is the one provided at initialization).
-- `lazy`: if true, returns a lazy enumerator.
+Let's look at [another example](https://github.com/Yuri-Rassokhin/flex-cartesian/tree/main/examples/09_ping_visualize). If we ping AWS DynamoDB, how do specific parameters influence the ping time? For this example, let's analyze geographic IP address and packet size.
 
-Each combination is passed as a `Struct` with fields matching the dimension names:
-```ruby
-s.cartesian { |v| puts "#{v.dim1} - #{v.dim2}" }
-```
+Here is the full code showing how FlexCartesian finds the answer:
 
----
-
-### Handling Functions
-```ruby
-func(command = :print, name = nil, hide: false, progress: false, title: "calculating functions", order: nil, &block)
-```
-- `command`: symbol, one of the following
-  - `:add` to add function as a virtual dimension to Cartesian space
-  - `:del` to delete function from Cartesian space
-  - `:print` as defaut action, prints all the functions added to Cartesian space
-  - `:run` to calculate all the functions defined for Cartesian space
-- `name`: symbol, name of the virtual dimension, e.g. `:my_function`
-- `hide`: flag that hides or shows the function in .output; it is useful to hide intermediate calculations
-- `progress`: show progress bar during `:run`, useful for large Cartesian space
-- `title`: title of the progress bar
-- `order`: can be `:first` or `:last` to make the function calculate before or after all other functions
-- `block`: a function that receives each vector and returns a computed value
-
-Functions show up in `.output` like additional (virtual) dimensions.
-
-> Note: functions must be calculated excpliticy using `:run` command.
-> Before the first calculation, a function has `nil` values in `.output`.
-> Explicit :run is reequired to unambigously control points in the execution flow where high computational resource is to be consumed.
-> Otherwise, automated recalculation of functions, perhaps, during `.output` would be a difficult-to-track computational burden.
-
-Example:
 ```ruby
-s = FlexCartesian.new( { dim1: [1, 2], dim2: ['A', 'B'] } )
-s.func(:add, :increment) { |v| v.dim1 + 1 }
-s.func(:run)
-
-s.output(format: :markdown)
-# | dim1 | dim2 | increment |
-# |------|------|--------|
-# | 1    | "A"  | 2    |
-# | 1    | "B"  | 2    |
-# ...
-```
-
+# enable FlexCartesian
+require 'flex-cartesian'
 
----
+# define parameter space
+space = FlexCartesian.new({
+  size: [64, 512, 1400, 1500, 4096, 8192],
+  target: [ "dynamodb.eu-central-1.amazonaws.com",   # Frankfurt
+	    "dynamodb.us-east-1.amazonaws.com",      # Virginia, US
+	    "dynamodb.sa-east-1.amazonaws.com",      # Sao Paolo
+	    "dynamodb.ap-northeast-1.amazonaws.com", # Tokio
+	    "dynamodb.af-south-1.amazonaws.com"]})   # Capetown
 
-### Count Total Combinations
-```ruby
-size(dims = nil) → Integer
-```
-Returns the number of possible combinations.
+# define behavioural functions:
+# 1. 'command' constructs ping command
+# 2. 'raw' executes the command and returns raw result
+# 3. 'time' extracts ping time from the result
+# 4. 'cap' is a fancy stuff, it shows 150 ms ping threshold on the future visialization.
+result = {}
+space.func(:add, :command) { |v| "ping -c #{v.count} -s #{v.size} -i #{v.interval} #{v.target}" }
+space.func(:add, :raw, hide: true) { |v| result[v.command] ||= `#{v.command} 2>&1` }
+space.func(:add, :time) { |v| v.raw[/min\/avg\/max\/(?:mdev|stddev) = [^\/]+\/([^\/]+)/, 1]&.to_f.round(2) }
+space.func(:add, :cap) { |v| 150 }
 
----
+# Now we compute all the functions in the parameter space
+space.func(:run, progress: true)
 
-### Convert to Array
-```ruby
-to_a(limit: nil) → Array
+# Visualize behavioural blueprint as a 2D-heatmap
+# It will show two functions - ping time (:time) and 150ms threashold (:cap)
+space.visualize(x: :size, y: :target, func: [ :time, :cap ], output: "./viz.html")
 ```
-- `limit`: maximum number of combinations to collect.
 
----
+By running this code, you'll generate an interactive HTML heatmap `./viz.html` illustrating how geography and packet size affect ping times to DynamoDB.
+
+As you can see, FlexCartesian's expressive DSL packs complex system profiling into simple one-liners.
+If you need a mathematically rigorous assessment of these parameters, simply add one more line:
 
-### Iterate with Progress Bar
 ```ruby
-progress_each(dims = nil, lazy: false, title: "Processing") { |v| ... }
+space.analyzer(:morris, trajectories: 10, step: 0.1, seed: 42).output(func: :time)
 ```
-Displays a progress bar using `ruby-progressbar`.
 
----
+This applies [Morris sensitivity analysis](https://en.wikipedia.org/wiki/Morris_method) directly to the behavioural blueprint extracted by FlexCartesian.
 
-### Generate Output
-```ruby
-output(separator: " | ", colorize: false, align: true, format: :plain, limit: nil, file: nil)
-```
-- `separator`: how to visually separate columns in the output
-- `colorize`: whether to colorize output or not
-- `align`: whether to align output by column or not
-- `format`: one of `:plain`, `:markdown`, or `:csv`
-- `limit`: break the output after the first `limit` Cartesian combinations
-- `file`: print to `file`
-
-Prints all combinations in table form (plain/markdown/CSV).  
-Markdown example:
-```markdown
-| dim1 | dim2 |
-|------|------|
-|  1   | "a"  |
-|  2   | "b"  |
-```
+## API Documentation
 
-```ruby
-dimensions(data = @dimensions, raw: false, separator: ', ', dimensions: true, values: true)
-```
-Generates formatted Cartesian dimensions or vectors of Cartesian space
-- `data`: what to format, either Cartesian vector (usually `s.cartesian { |v| ... }) or entire Cartesian dimensions
-- `raw`: if enabled, overrides any other formarring flags and returns the same as `.inspect`
-- `separator`: how to separate individual components
-- `dimensions`: whether or not show dimension names
-- `values`: whether or not show value(s) associated with dimensions
+Detailed API documentation is available [here](docs/api/api.md).
 
----
+## Installation
 
-### Import from JSON or YAML
-```ruby
-import(path, format: :json)
+```bash
+gem install flex-cartesian
 ```
-- `path`: input file
-- `format`: format to read, `:json` and `:yaml` supported
 
-Obsolete import methods:
-```ruby
-s.from_json("file.json")
-s.from_yaml("file.yaml")
-```
+## Status
 
----
+This project is actively developed. Please [submit](https://github.com/Yuri-Rassokhin/flex-cartesian/issues) your feature requests or bug reports. 
 
-### Export to JSON or YAML
-```ruby
-export(path, format: :json)
-```
-- `path`: output file
-- `format`: format to export, `:json` and `:yaml` supported
+## Contributing
 
-### Conditions on Cartesian Space
-```ruby
-cond(command = :print, index: nil, &block)
-```
-- `command`: one of the following
-  - `:set` to set the condition to Cartesian space
-  - `:unset` to remove the `index` condition from Cartesian space
-  - `:clear` to remove all conditions from Cartesian space
-  - `:print` default command, prints all the conditions on the Cartesian space
-- `index`: index of the condition set to Cartesian space, it is used to remove specified condition
-- `block`: definition of the condition, it should return `true` or `false` to avoid unpredictable behavior
-
-Example:
-```ruby
-s.cond(:set) { |v| v.dim1 > v.dim3 }
-s.cond # defaults to s.cond(:print) and shows all the conditions in the form 'index | definition'
-s.cond(:unset, 0) # remove the condition
-s.cond(:clear) # remove all conditions, if any
-```
+Bug reports and pull requests are welcome on [GitHub](https://github.com/Yuri-Rassokhin/flex-cartesian).
+
+If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".
 
+1. Fork the Project
+2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the Branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
 
+This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to standard open-source etiquette.
 
 ## License
 
-This project is licensed under the terms of the GNU General Public License v3.0.  
-See [LICENSE](LICENSE) for more details.
+This project is licensed under the terms of the GNU General Public License v3.0. See [LICENSE](LICENSE) for more details.