flex-cartesian 0.1.9 → 1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b26211b52fac8e2a26ff5408d422e6ae328aefbd67d0a18ac07ef0404006c05
-  data.tar.gz: cf406e24632a26605b5002e91ddfdf63bddaeb0a361d2dbbab76f5514bfdec88
+  metadata.gz: 4b8d43af751cdba0a5c141bab0606576291395a5cc3e3a8cb673bacc86c2920b
+  data.tar.gz: 96bfd43d1328e48d38665c2c4aa3b951cf24b932c510ab73ed704d7b7bf98c10
 SHA512:
-  metadata.gz: 2cb31e4b65dba494aeac390ad1baee384c5eca90aeb67363cb374db4ba0c1e4b4d4f4dc6acac088642a751e9d7d4ee996b98c99abf49fdc98c615981c5c12663
-  data.tar.gz: 2b9c27d532a24430cbd21508d91d02d2f29172d9069eab75a8af5c60a2fb25936ff014de5ffc6c5a7df29e08d07de1b7272aefb6edbc907f60a96ae1e1520236
+  metadata.gz: 6ff1dbb6deb67e9c9a997d8fb4cea7bb75f8fb4aa9ef8ade0a2452c413e19f97c8687f7816c68d47bef8711fe9cdec98159aae2d80ab468ca55512675f4fd5b3
+  data.tar.gz: 16764e02f4010d4c6431779f8cb2f9b7e11f6f04b97ac0c7546f5b1431e287936b92207a527a9838ab614aeed635f290e268961c235fbc83553eef4e448c2358

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 1.0 - 2025-07-14
+### Added
+- Optional flad for hiding function from output
+
+### Fixed
+- Simplified default parameters
+- Unified umbrella method for handling functions
+- Initialization directly from file of dimensions
+
+## 0.2 - 2025-07-12
+### Added
+- Logical conditions on Cartesian space
+
 ## 0.1.9 - 2025-07-08
 ### Fixed
 - Documentation

data/README.md

@@ -12,6 +12,8 @@
 
 ✅ Functions over Cartesian vectors are decoupled from dimensionality
 
+✅ Define conditions on Cartesian combinations using `s.cond(:set) { |v| v.dim1 > v.dim2 } }` syntax
+
 ✅ Calculate over named dimensions using `s.cartesian { |v| puts "#{v.dim1} and #{v.dim2}" }` syntax
 
 ✅ Add functions over dimensions using `s.add_function { |v| v.dim1 + v.dim2 }` syntax
@@ -42,7 +44,7 @@ gem install flex-cartesian-*.gem
 
 ## Usage
 
-```
+```ruby
 #!/usr/bin/ruby
 
 require 'flex-cartesian'
@@ -51,6 +53,9 @@ 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],
@@ -69,6 +74,12 @@ 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) }
 
@@ -85,6 +96,12 @@ 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 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.
+
 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) }
@@ -97,6 +114,28 @@ s.remove_function(:test)
 
 
 
+# CONDITIONS ON CARTESIAN SPACE
+
+# 8. A condition is a logical restriction of allowed combitnations for 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"
@@ -125,7 +164,7 @@ s.export('example.yaml', format: :yaml)
 # UTILITIES
 
 puts "\nGet number of Cartesian combinations"
-puts "Note: .size counts only dimenstions, it ignores functions"
+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:"
@@ -133,7 +172,120 @@ 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:
+
+```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
+  ]
+}
+```
+
+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
+
+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
+
+# 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
+
+# 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
+
+# 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
+
+# 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
+
+# this is the spinal axis of FlexCartesian:
+# calculate all functions on the entire Cartesian space of parameters aka dimensions
+s.func(:run)
+
+# save benchmark results to CSV for convenient analysis in BI tools
+s.output(format: :csv, file: './benchmark.csv')
+
+# for convenience, show tabular result on screen as well
+s.output(colorize: true)
+```
+
+This code is 100% practical and illustrative. You can benchmark:
+
+- 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
+
+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.
 
+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).
 
 ## API Overview
 
@@ -278,6 +430,25 @@ Example:
 s.cartesian { |v| v.output(colorize: true, align: false) }
 ```
 
+---
+
+### 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
+     )
+```
+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(:clear) # remove all conditions, if any
+```
+
+
+
 ## License
 
 This project is licensed under the terms of the GNU General Public License v3.0.  

data/lib/flex-cartesian.rb

@@ -3,6 +3,8 @@ require 'progressbar'
 require 'colorize'
 require 'json'
 require 'yaml'
+require 'method_source'
+require 'set'
 
 module FlexOutput
   def output(separator: " | ", colorize: false, align: true)
@@ -25,11 +27,77 @@ end
 class FlexCartesian
   attr :dimensions
 
-  def initialize(dimensions = nil)
+  def initialize(dimensions = nil, path: nil, format: :json)
+    if dimensions && path
+      $logger.msg "Please specify either dimensions or path to dimensions", :error
+    end
     @dimensions = dimensions
+    @conditions = []
     @derived = {}
+    @function_results = {}  # key: Struct instance.object_id => { fname => value }
+    @function_hidden = Set.new
+    import(path, format: format) if path
+  end
+
+  def cond(command = :print, index: nil, &block)
+    case command
+    when :set
+      raise ArgumentError, "Block required" unless block_given?
+      @conditions << block
+      self
+    when :unset
+      raise ArgumentError, "Index of the condition required" unless index
+      @conditions.delete_at(index)
+    when :clear 
+      @conditions.clear
+      self
+    when :print 
+      return if @conditions.empty?
+      @conditions.each_with_index { |cond, idx| puts "#{idx} | #{cond.source.gsub(/^.*?\s/, '')}" }
+    else
+      raise ArgumentError, "unknown condition command: #{command}"
+    end
   end
 
+def func(command = :print, name = nil, hide: false, &block)
+  case command
+  when :add
+    raise ArgumentError, "Function name and block required for :add" unless name && block_given?
+    add_function(name, &block)
+    @function_hidden.delete(name.to_sym)
+    @function_hidden << name.to_sym if hide
+
+  when :del
+    raise ArgumentError, "Function name required for :del" unless name
+    remove_function(name)
+
+  when :print
+    if @derived.empty?
+      puts "(no functions defined)"
+    else
+      @derived.each do |fname, fblock|
+        source = fblock.source rescue '(source unavailable)'
+
+        body = source.sub(/^.*?\s(?=(\{|\bdo\b))/, '').strip
+
+        puts "  #{fname.inspect.ljust(12)}| #{body}#{@function_hidden.include?(fname) ? ' [HIDDEN]' : ''}"
+      end
+    end
+
+  when :run
+    @function_results = {}
+    cartesian do |v|
+      @function_results[v] ||= {}
+      @derived.each do |fname, block|
+        @function_results[v][fname] = block.call(v)
+      end
+    end
+
+  else
+    raise ArgumentError, "Unknown command for function: #{command.inspect}"
+  end
+end
+
   def add_function(name, &block)
     raise ArgumentError, "Block required" unless block_given?
     @derived[name.to_sym] = block
@@ -61,18 +129,26 @@ class FlexCartesian
       struct_instance.define_singleton_method(name) { block.call(struct_instance) }
     end
 
+  next if @conditions.any? { |cond| !cond.call(struct_instance) }
+
     yield struct_instance
   end
 end
 
-  def size(dims = nil)
-    dimensions = dims || @dimensions
-    return 0 unless dimensions.is_a?(Hash)
-
-    values = dimensions.values.map { |dim| dim.is_a?(Enumerable) ? dim.to_a : [dim] }
-    return 0 if values.any?(&:empty?)
-
-    values.map(&:size).inject(1, :*)
+  def size
+    return 0 unless @dimensions.is_a?(Hash)
+    if @conditions.empty?
+      values = @dimensions.values.map { |dim| dim.is_a?(Enumerable) ? dim.to_a : [dim] }
+      return 0 if values.any?(&:empty?)
+      values.map(&:size).inject(1, :*)
+    else
+      size = 0
+      cartesian do |v|
+        next if @conditions.any? { |cond| !cond.call(v) }
+        size += 1
+      end
+      size
+    end
   end
 
   def to_a(limit: nil)
@@ -84,46 +160,71 @@ end
     result
   end
 
-  def progress_each(dims = nil, lazy: false, title: "Processing")
-    total = size(dims)
-    bar = ProgressBar.create(title: title, total: total, format: '%t [%B] %p%% %e')
+  def progress_each(lazy: false, title: "Processing")
+    bar = ProgressBar.create(title: title, total: size, format: '%t [%B] %p%% %e')
 
-    cartesian(dims, lazy: lazy) do |v|
+    cartesian(@dimensions, lazy: lazy) do |v|
       yield v
       bar.increment
     end
   end
 
-  def output(separator: " | ", colorize: false, align: true, format: :plain, limit: nil)
-  rows = []
-  cartesian do |v|
-    rows << v
-    break if limit && rows.size >= limit
-  end
+def output(separator: " | ", colorize: false, align: true, format: :plain, limit: nil, file: nil)
+  rows = if @function_results && !@function_results.empty?
+           @function_results.keys
+         else
+           result = []
+           cartesian do |v|
+             result << v
+             break if limit && result.size >= limit
+           end
+           result
+         end
+
   return if rows.empty?
 
-  headers = (
-    rows.first.members +
-    rows.first.singleton_methods(false).reject { |m| m.to_s.start_with?('__') }
-  ).map(&:to_s)
+  visible_func_names = @derived.keys - (@function_hidden || Set.new).to_a
+  headers = rows.first.members.map(&:to_s) + visible_func_names.map(&:to_s)
 
   widths = align ? headers.to_h { |h|
-    [h, [h.size, *rows.map { |r| fmt_cell(r.send(h), false).size }].max]
+    values = rows.map do |r|
+      val = if r.members.map(&:to_s).include?(h)
+              r.send(h)
+            else
+              @function_results&.dig(r, h.to_sym)
+            end
+      fmt_cell(val, false).size
+    end
+    [h, [h.size, *values].max]
   } : {}
 
+  lines = []
+
+  # Header
   case format
   when :markdown
-    puts "| " + headers.map { |h| h.ljust(widths[h] || h.size) }.join(" | ") + " |"
-    puts "|-" + headers.map { |h| "-" * (widths[h] || h.size) }.join("-|-") + "-|"
+    lines << "| " + headers.map { |h| h.ljust(widths[h] || h.size) }.join(" | ") + " |"
+    lines << "|-" + headers.map { |h| "-" * (widths[h] || h.size) }.join("-|-") + "-|"
   when :csv
-    puts headers.join(",")
+    lines << headers.join(",")
   else
-    puts headers.map { |h| fmt_cell(h, colorize, widths[h]) }.join(separator)
+    lines << headers.map { |h| fmt_cell(h, colorize, widths[h]) }.join(separator)
   end
 
+  # Rows
   rows.each do |row|
-    line = headers.map { |h| fmt_cell(row.send(h), colorize, widths[h]) }
-    puts format == :csv ? line.join(",") : line.join(separator)
+    values = row.members.map { |m| row.send(m) } +
+             visible_func_names.map { |fname| @function_results&.dig(row, fname) }
+
+    line = headers.zip(values).map { |(_, val)| fmt_cell(val, colorize, widths[_]) }
+    lines << (format == :csv ? line.join(",") : line.join(separator))
+  end
+
+  # Output to console or file
+  if file
+    File.write(file, lines.join("\n") + "\n")
+  else
+    lines.each { |line| puts line }
   end
 end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: flex-cartesian
 version: !ruby/object:Gem::Version
-  version: 0.1.9
+  version: '1.0'
 platform: ruby
 authors:
 - Yury Rassokhin
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-07-08 00:00:00.000000000 Z
+date: 2025-07-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: colorize
@@ -52,10 +52,24 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: method_source
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
 description: 'Flexible and human-friendly Cartesian product enumerator for Ruby. Supports
-  functions on cartesian, dimensionality-agnostic/dimensionality-aware iterators,
-  named dimensions, tabular output, lazy/eager evaluation, progress bar, import from
-  JSON/YAML, and export to Markdown/CSV. Code example: https://github.com/Yuri-Rassokhin/flex-cartesian/blob/main/README.md#usage'
+  functions and conditions on cartesian, dimensionality-agnostic/dimensionality-aware
+  iterators, named dimensions, tabular output, lazy/eager evaluation, progress bar,
+  import from JSON/YAML, and export to Markdown/CSV. Code example: https://github.com/Yuri-Rassokhin/flex-cartesian/blob/main/README.md#example'
 email:
 - yuri.rassokhin@gmail.com
 executables: []
@@ -80,7 +94,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="