flex-cartesian 0.2 → 1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4b34c40aea1692a248f2f4ee506b8b7a5a66a8257f90b1f74a7613897f8047c4
-  data.tar.gz: 3fb4c691a65ebcda1f9606368f436ba1ebee56749dee9e27d04296884cfef26e
+  metadata.gz: 4b8d43af751cdba0a5c141bab0606576291395a5cc3e3a8cb673bacc86c2920b
+  data.tar.gz: 96bfd43d1328e48d38665c2c4aa3b951cf24b932c510ab73ed704d7b7bf98c10
 SHA512:
-  metadata.gz: 455053108bada48ae9b224879069cfe6e43fca419391e194f5b90dbaece0523ab7810eb471e1768814c17bc61f4952171493fb5c38283473d7798039f6b8b8dd
-  data.tar.gz: 63ebb02a0fb22162b67d17caf483ab2abc3499e9d072ddec3749124e82856d4bfcf3106fbe53b84fd927fe3b36279cb1b2103d75064d4a1cf393ab2f72912f38
+  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

@@ -172,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
 
@@ -320,10 +433,12 @@ 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 }

data/lib/flex-cartesian.rb

@@ -4,6 +4,7 @@ require 'colorize'
 require 'json'
 require 'yaml'
 require 'method_source'
+require 'set'
 
 module FlexOutput
   def output(separator: " | ", colorize: false, align: true)
@@ -26,10 +27,16 @@ 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)
@@ -52,6 +59,45 @@ class FlexCartesian
     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
@@ -123,36 +169,62 @@ end
     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.2'
+  version: '1.0'
 platform: ruby
 authors:
 - Yury Rassokhin
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-07-12 00:00:00.000000000 Z
+date: 2025-07-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: colorize
@@ -69,7 +69,7 @@ dependencies:
 description: 'Flexible and human-friendly Cartesian product enumerator for Ruby. Supports
   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#usage'
+  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: []
@@ -94,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:
   - - ">="