flex-cartesian 1.0 → 1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4b8d43af751cdba0a5c141bab0606576291395a5cc3e3a8cb673bacc86c2920b
-  data.tar.gz: 96bfd43d1328e48d38665c2c4aa3b951cf24b932c510ab73ed704d7b7bf98c10
+  metadata.gz: b89541266e2ac802592bc652ddbf2edffe1aea4e47ab1d732e2623ad2cc5835b
+  data.tar.gz: d717084b70f95af0e3f5706a426731685cc0cc7ddcba038b15b662d2d3226b3b
 SHA512:
-  metadata.gz: 6ff1dbb6deb67e9c9a997d8fb4cea7bb75f8fb4aa9ef8ade0a2452c413e19f97c8687f7816c68d47bef8711fe9cdec98159aae2d80ab468ca55512675f4fd5b3
-  data.tar.gz: 16764e02f4010d4c6431779f8cb2f9b7e11f6f04b97ac0c7546f5b1431e287936b92207a527a9838ab614aeed635f290e268961c235fbc83553eef4e448c2358
+  metadata.gz: 26b83b8486d89c151ae8fbc23b7ed9c19f5417a582fd6843b9e654264f0e1deb2615686fe6872b053252c9059a843ca416c41a97ccbc546de3da32b0228b7c61
+  data.tar.gz: aa43ccd2936336564a8b14e70a6142167a17db9b93e646ea56445f25b477cd95c8a219fdeac383801c71ea4a07210c00fb1ecbd67d51f18e97afe7ad7b01c8da

data/README.md

@@ -2,25 +2,23 @@
 
 **Ruby implementation of flexible and human-friendly operations on Cartesian products**  
 
-
-
 ## Features
 
 ✅ Named dimensions with arbitrary keys
 
-✅ Enumerate over Cartesian product with a single block argument  
+✅ Enumerate over Cartesian space with a single block argument  
 
-✅ Functions over Cartesian vectors are decoupled from dimensionality
+✅ Actions on Cartesian are decoupled from dimensionality: `s.cartesian { |v| do_something(v) }`
 
-✅ Define conditions on Cartesian combinations using `s.cond(:set) { |v| v.dim1 > v.dim2 } }` syntax
+✅ Conditions for Cartesian space: `s.cond(:set) { |v| v.dim1 > v.dim2 } }`
 
-✅ Calculate over named dimensions using `s.cartesian { |v| puts "#{v.dim1} and #{v.dim2}" }` syntax
+✅ Calculation over named dimensions: `s.cartesian { |v| puts "#{v.dim1} and #{v.dim2}" }`
 
-✅ Add functions over dimensions using `s.add_function { |v| v.dim1 + v.dim2 }` syntax
+✅ Functions on Cartesian space: `s.func(:add, :my_sum) { |v| v.dim1 + v.dim2 }`
 
 ✅ Lazy and eager evaluation
 
-✅ Progress bars for large Cartesian combinations
+✅ Progress bars for large Cartesian spaces
 
 ✅ Export of Cartesian space to Markdown or CSV
 
@@ -30,7 +28,77 @@
 
 ✅ Structured and colorized terminal output  
 
+## Use Cases
+
+`FlexCartesian` is especially useful in the following scenarios.
+
+### 1. Sweep Analysis of Performance
+
+Systematically evaluate an application or algorithm across all combinations of parameters:
+
+- Parameters: `threads`, `batch_size`, `backend`, etc
+- Metrics: `throughput`, `latency`, `memory`
+- Output: CSV or Markdown tables
+
+### 2. Hyperparameter Tuning for ML Models
+
+Iterate over all combinations of hyperparameters:
+
+- 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
+
+### 3. Infrastructure and System Configuration
+
+Generate all valid infrastructure configurations:
+
+```ruby
+region:   ["us-west", "eu-central"]
+tier:     ["basic", "pro"]
+replicas: [1, 3, 5]
+```
+
+With conditions like "basic tier cannot have more than one replica:
+```ruby
+s.cond(:set) { |v| (v.tier == "basic" ? v.replicas == 1 : true) }
+```
+
+### 4. Mass Testing of CLI Commands
+Generate and benchmark all valid CLI calls:
+
+```bash
+myapp --threads=4 --batch=32 --backend=torch
+```
+
+Capture runtime, output, errors, etc.
+
+### 5. Input Generation for UI/API Testing
+Automatically cover input parameter spaces for:
+
+- HTTP methods: ["GET", "POST"]
+- User roles: ["guest", "user", "admin"]
+- Language settings: ["en", "fr", "de"]
 
+### 6. Scientific and Engineering Simulations
+Generate multidimensional experimental spaces for:
+
+- Physics simulations
+- Bioinformatics parameter sweeps
+- Network behavior modeling, etc
+
+### 7. Structured Reporting and Visualization
+Output Cartesian data as:
+
+- Markdown (for GitHub rendering)
+- CSV (for Excel, Google Sheets, and more advanced BI tools)
+- Plain text (for CLI previews)
+
+### 8. Test Case Generation
+Use it to drive automated test inputs for:
+
+- RSpec shared examples
+- Minitest table-driven tests
+- PyTest parameterization
 
 ## Installation
 
@@ -98,25 +166,24 @@ s.cartesian(lazy: true).take(2).each { |v| do_something(v) }
 
 # 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 method.
-# 7. However, functions remains virtual construct, and their values can't be referenced by name
-#    (unlike regular dimensions). Also, functions do not add to .size of 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.add_function(:triple) { |v| v.dim1 * 3 + (v.dim3 ? 1: 0) }
-# Note: however, function remains a virtual construct, and it cannot be referenced by name
+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.add_function(:test) { |v| v.dim3.to_i }
-s.remove_function(:test)
+s.func(:add, :test) { |v| v.dim3.to_i }
+s.func(:del, :test)
 
 
 
 # CONDITIONS ON CARTESIAN SPACE
 
-# 8. A condition is a logical restriction of allowed combitnations for 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.
 
@@ -140,10 +207,8 @@ puts "Restored size without conditions: #{s.size}"
 
 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)
 
@@ -155,7 +220,6 @@ 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)
 
@@ -166,7 +230,6 @@ s.export('example.yaml', format: :yaml)
 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
@@ -218,62 +281,40 @@ These input parameters form the following dimensions.
 }
 ```
 
-Note that '//' isn't officially supported by JSON, and you may want to remove the comments if you experience parser errors.
+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.
 
 ```ruby
 require 'flex-cartesian'
 
-s = FlexCartesian.new(path: './ping_config.json') # file with the parameters as given above
+s = FlexCartesian.new(path: './ping_parameters.json') # file with the parameters as given above
 
-result = {} # here we will store raw result of each ping and fetch target metrics from it
-
-# this function shows actual ping command
-s.func(:add, :command) do |v|
-  "ping -c #{v.count} -s #{v.size} #{v.target}"
-end
+result = {} # raw result of each ping
 
-# this function gets raw result of actual ping command
-s.func(:add, :raw_ping, hide: true) do |v|
-  result[v.command] ||= `#{v.command} 2>&1`
-end
+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
 
-# this function extracts ping time
-s.func(:add, :time) do |v|
-  if v.raw_ping =~ /min\/avg\/max\/(?:mdev|stddev) = [^\/]+\/([^\/]+)/
-    $1.to_f
-  end
-end
+s.func(:run) # Sweep analysis! Benchmark all possible combinations of parameters
 
-# this function extracts minimum ping time
-s.func(:add, :min) do |v|
-  if v.raw_ping =~ /min\/avg\/max\/(?:mdev|stddev) = ([^\/]+)/
-    $1.to_f
-  end
-end
+s.output(format: :csv, file: './result.csv') # save benchmark result as CSV
 
-# funally, this function extracts losses of ping
-s.func(:add, :loss) do |v|
-  if v.raw_ping =~ /(\d+(?:\.\d+)?)% packet loss/
-    $1.to_f
-  end
-end
+s.output(colorize: true) # for convenience, show result in terminal
+```
 
-# this is the spinal axis of FlexCartesian:
-# calculate all functions on the entire Cartesian space of parameters aka dimensions
-s.func(:run)
+If you run the code, after a while it will generate benchmark results on the screen:
 
-# save benchmark results to CSV for convenient analysis in BI tools
-s.output(format: :csv, file: './benchmark.csv')
+![Ping Benchmark Example](doc/ping_benchmark_example.png)
 
-# for convenience, show tabular result on screen as well
-s.output(colorize: true)
-```
+Additionally, CSV version of this result is saved as `./benchmark.csv`
 
-This code is 100% practical and illustrative. You can benchmark:
+The PING benchmarking code above is 100% practical and illustrative.
+You can modify it and benchmark virtually anything:
 
-- Local block devices using 'dd'
-- GPU-to-Storage connection using 'gdsio'
+- 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
@@ -285,15 +326,19 @@ In any use case, FlexCartesian will unfold complete landscape of the target perf
 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.
 
-Here is an example of how I used FlexCartesian to [analyze optimal performance/cost of YOLO](https://www.linkedin.com/pulse/comparing-gpu-a10-ampere-a1-shapes-object-oci-yuri-rassokhin-rseqf).
+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).
+
+
 
 ## API Overview
 
 ### Initialization
 ```ruby
-FlexCartesian.new(dimensions_hash)
+FlexCartesian.new(dimensions = nil, path: nil, format: :json)
 ```
-- `dimensions_hash`: a hash with named dimensions; each value can be an `Enumerable` (e.g., arrays, ranges).
+- `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
@@ -309,10 +354,11 @@ FlexCartesian.new(dimensions)
 ---
 
 ### Iterate Over All Combinations
+
+Example:
 ```ruby
 # With block
 cartesian(dims = nil, lazy: false) { |vector| ... }
-
 # Without block: returns Enumerator
 cartesian(dims = nil, lazy: false)
 ```
@@ -326,20 +372,31 @@ s.cartesian { |v| puts "#{v.dim1} - #{v.dim2}" }
 
 ---
 
-### Add / Remove Functions
+### Handling Functions
 ```ruby
-add_function(name, &block)
-remove_function(name)
+func(command = :print, name = nil, hide: false, &block)
 ```
-- `name`: symbol — the name of the virtual dimension (e.g. `:label`)
+- `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
 - `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.add_function(:increment) { |v| v.dim1 + 1 }
+s.func(:add, :increment) { |v| v.dim1 + 1 }
+s.func(:run)
 
 s.output(format: :markdown)
 # | dim1 | dim2 | increment |
@@ -349,7 +406,6 @@ s.output(format: :markdown)
 # ...
 ```
 
-> Note: functions are virtual — they are not part of the base dimensions, but they integrate seamlessly in output.
 
 ---
 
@@ -377,19 +433,20 @@ Displays a progress bar using `ruby-progressbar`.
 
 ---
 
-### Print Table to Console
+### Print Cartesian
 ```ruby
-output(
-  separator: " | ",
-  colorize: false,
-  align: false,
-  format: :plain  # or :markdown, :csv
-  limit: nil
-)
+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"  |
@@ -400,9 +457,10 @@ Markdown example:
 
 ### Import from JSON or YAML
 ```ruby
-import('file.json',
-  format: :json) # or :yaml
+import(path, format: :json)
 ```
+- `path`: input file
+- `format`: format to read, `:json` and `:yaml` supported
 
 Obsolete import methods:
 ```ruby
@@ -412,38 +470,30 @@ s.from_yaml("file.yaml")
 
 ---
 
-### Export from JSON or YAML
-```ruby
-export('file.json',
-  format: :json) # or :yaml
-```
-
----
-
-### Print Cartesian Space
-Each yielded combination is a `Struct` extended with:
-```ruby
-output(separator: " | ", colorize: false, align: true)
-```
-Example:
+### Export to JSON or YAML
 ```ruby
-s.cartesian { |v| v.output(colorize: true, align: false) }
+export(path, format: :json)
 ```
-
----
+- `path`: output file
+- `format`: format to export, `:json` and `:yaml` supported
 
 ### Conditions on Cartesian Space
 ```ruby
-cond(command = :print, # or :set, :unset, :clear
-     index: nil, # index of a conditions to unset
-     &block # defintiion of the condition to set
-     )
+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 previously set condition
+s.cond(:unset, 0) # remove the condition
 s.cond(:clear) # remove all conditions, if any
 ```
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: flex-cartesian
 version: !ruby/object:Gem::Version
-  version: '1.0'
+  version: '1.1'
 platform: ruby
 authors:
 - Yury Rassokhin
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-07-14 00:00:00.000000000 Z
+date: 2025-07-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: colorize
@@ -38,6 +38,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.13'
+- !ruby/object:Gem::Dependency
+  name: progressbar
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
 - !ruby/object:Gem::Dependency
   name: json
   requirement: !ruby/object:Gem::Requirement