carray-jit 0.1.0 → 0.1.2

data/lib/carray/jit/analyzer.rb

@@ -179,6 +179,9 @@ class CArray
       # radius, kept per side because a window need not be symmetric.  It is
       # what the caller walks the interior by.
       attr_reader :window_reach
+      # The same, per window: what one array is reached into, rather than the
+      # widest reach over all of them.
+      attr_reader :window_reaches
       # The names the block gave its windows, which are the arrays a border
       # rule applies to: the ones the block reaches away from the cell in.
       attr_reader :windows
@@ -233,10 +236,18 @@ class CArray
       # returned, and it reaches no array.  It is the smallest of the three --
       # with no cell to address there is no extent, no direction and no mask,
       # so most of what follows never runs.
+      # `free_indices` are the result's axes, named at the call site rather
+      # than taken from the block's parameters.  Naming them puts the
+      # contraction in its explicit form: these are free however often they
+      # appear, and a parameter is summed by repeating as it is under the
+      # convention.  Nil is "nothing was named" and an empty list is "named,
+      # and none of them are free" -- which is a contraction to a single
+      # number, and is not the same statement.
       def initialize (source, node: nil, array_names: [], c_functions: {}, rank: nil,
                       steps: nil, contract: false, result: nil, function: false,
                       pointers: {}, map: false, cell_names: [],
-                      recursion: nil, windows: [], returns: true)
+                      recursion: nil, windows: [], returns: true,
+                      free_indices: nil)
         @source = source
         @node = node
         @array_names = array_names
@@ -277,6 +288,12 @@ class CArray
         @whole_array = false
         # How far the windows reach on each axis, filled in as they are read.
         @window_reach = Array.new(rank.to_i) { [0, 0] }
+        # And how far each window reaches on its own.  The kernel walks the
+        # interior by the widest of them, but whether one array may be written
+        # in place is a question about that array's window alone.
+        @window_reaches = Hash.new { |reaches, name|
+          reaches[name] = Array.new(rank.to_i) { [0, 0] }
+        }
         @uses_undef = false
         @calls_for_effect = false
         @outer_names = []
@@ -293,6 +310,7 @@ class CArray
         @given_rank = rank
         @steps = steps
         @contract = contract
+        @free_indices = free_indices
         @result = result
         @contracted_names = []
         @free_names = []
@@ -544,10 +562,9 @@ class CArray
 
       # Turns `c[i,j] = a[i,k] * b[k,j]` into the loops it stands for.
       #
-      # Which indices are summed is not the assignment's business: an index
-      # that appears twice in the term is summed, and that repetition is the
-      # notation -- it is what stands in for the sigma.  An index appearing
-      # once is free.  The left-hand side says where the result goes and in
+      # Which indices are summed is not the assignment's business: a repeated
+      # index is summed, and that repetition is the notation -- it is what
+      # stands in for the sigma.  An index appearing once is free.  The left-hand side says where the result goes and in
       # what order its axes lie; it cannot make an index disappear.
       # The block's value is what every cell of the result gets, so the last
       # expression becomes a write into the result at the cell the loop is on.
@@ -641,8 +658,9 @@ class CArray
       end
 
       # Counts where each index sits on a tensor, on the right-hand side only.
-      # Once is free, twice is summed, and more than twice is not the
-      # convention -- it says nothing about which pair to sum.
+      # Once is free and repeated is summed, however often it repeats: three
+      # positions are not a pair to choose between but one index read at three
+      # of them, and `a[i,i,i]` is the sum along the cube's long diagonal.
       def classify_indices (statements, write)
         counts = Hash.new(0)
         subscripts_of(statements, write).each { |index, _| counts[index] += 1 }
@@ -653,16 +671,23 @@ class CArray
             "#{missing.map { |name| "`#{name}`" }.join(', ')} " \
             "#{missing.size == 1 ? 'names no axis' : 'name no axis'} here")
         end
-        crowded = counts.select { |_, count| count > 2 }.keys
-        unless crowded.empty?
-          raise Unsupported.new(
-            "#{crowded.map { |name| "`#{name}`" }.join(', ')} appears more " \
-            "than twice; a contraction sums a pair, and there is no pair to " \
-            "choose")
+        # Naming the result's axes says which indices are free; it does not
+        # say what a repetition means, and a repetition still means a sum.  So
+        # a named index is free however often it appears -- twice is what a
+        # point number does, and `square[a,a]` is the diagonal rather than a
+        # trace -- while a parameter is summed by repeating, here as under the
+        # convention.  One that appears once is free and was not named, which
+        # is a sum along an axis and is not a contraction.
+        if @free_indices
+          parameters = @index_names - @free_indices
+          alone = parameters.select { |name| counts[name] == 1 }
+          unless alone.empty?
+            raise Unsupported.new(describe_a_lone_parameter(alone))
+          end
+          return [@free_indices, parameters]
         end
-
         [@index_names.select { |name| counts[name] == 1 },
-         @index_names.select { |name| counts[name] == 2 }]
+         @index_names.select { |name| counts[name] > 1 }]
       end
 
       # Every subscript on the right-hand side: the summand, and whatever the
@@ -681,20 +706,44 @@ class CArray
         collected.reject { |index, _| index.nil? }
       end
 
+      # A parameter at one position only.  Nothing there stands in for a
+      # sigma, so summing it would be the argument list quietly meaning more
+      # than it says -- the same reason the convention refuses it.
+      def describe_a_lone_parameter (alone)
+        listed = alone.map { |name| "`#{name}`" }.join(", ")
+        named = (@free_indices + alone).map { |name| ":#{name}" }.join(", ")
+        "#{listed} #{alone.size == 1 ? 'appears' : 'appear'} once, so " \
+        "#{alone.size == 1 ? 'it is' : 'they are'} free rather than summed. " \
+        "A contraction sums the indices that repeat; name " \
+        "#{alone.size == 1 ? 'it' : 'them'} as " \
+        "#{alone.size == 1 ? 'an axis' : 'axes'} of the result " \
+        "(`CArray.jit_contract(#{named})`) to keep " \
+        "#{alone.size == 1 ? 'it' : 'them'}, or use sum(axis:) to sum along " \
+        "the axis"
+      end
+
       def describe_index_mismatch (written, free, summed)
         summed_on_left = written & summed
         unless summed_on_left.empty?
+          # What to name is the whole left-hand side, in its order: those are
+          # the result's axes, and the one that repeats is only the reason
+          # the convention could not see it.
+          named = written.map { |name| ":#{name}" }.join(", ")
           return "#{summed_on_left.map { |name| "`#{name}`" }.join(', ')} " \
-                 "#{summed_on_left.size == 1 ? 'appears' : 'appear'} twice on " \
-                 "the right, so #{summed_on_left.size == 1 ? 'it is' : 'they are'} " \
-                 "summed over and cannot also be free"
+                 "#{summed_on_left.size == 1 ? 'is repeated' : 'are repeated'} " \
+                 "on the right, so #{summed_on_left.size == 1 ? 'it is' : 'they are'} " \
+                 "summed over and cannot also be free. That a repeated index " \
+                 "is summed is the convention for dimensions; an index " \
+                 "that numbers things -- a point, a sample -- is not one, and " \
+                 "naming the result's axes says so: " \
+                 "`CArray.jit_contract(#{named})`"
         end
         dropped = free - written
         "#{dropped.map { |name| "`#{name}`" }.join(', ')} " \
         "#{dropped.size == 1 ? 'appears' : 'appear'} once, so " \
         "#{dropped.size == 1 ? 'it is' : 'they are'} free and must be on the " \
-        "left. A contraction sums the indices that appear twice; to sum one " \
-        "that does not, write the loop with jit_for, or use sum(axis:)"
+        "left. A contraction sums the indices that repeat; to sum one that " \
+        "does not, write the loop with jit_for, or use sum(axis:)"
       end
 
       # The sum starts from zero of whatever the summand is; which zero that
@@ -714,9 +763,16 @@ class CArray
 
       private
 
+      # The accumulator is a local this writes rather than one the block
+      # named, so it has to avoid every name that is already something: the
+      # block's locals, and the indices -- an index called `contraction` would
+      # have shared the identifier with the accumulator and the sum would have
+      # come out zero, with nothing said.
       def free_local_name
+        taken = @local_names + @index_names + @outer_names + @inner_names +
+                @contracted_names
         name = :contraction
-        name = :"#{name}_" while @local_names.include?(name)
+        name = :"#{name}_" while taken.include?(name)
         name
       end
 
@@ -777,6 +833,27 @@ class CArray
           return
         end
 
+        if @contract && @free_indices
+          # The explicit form: the result's axes were named at the call site,
+          # so what the block names are the indices that are summed -- and a
+          # contraction may now take no parameters at all, which is how the
+          # diagonal of one array is written.
+          summed = requireds.map(&:name)
+          both = @free_indices & summed
+          unless both.empty?
+            raise Unsupported.new(
+              "#{both.map { |name| "`#{name}`" }.join(', ')} " \
+              "#{both.size == 1 ? 'is' : 'are'} named as " \
+              "#{both.size == 1 ? 'an axis' : 'axes'} of the result and again " \
+              "as a block parameter; the parameters are the indices that are " \
+              "summed")
+          end
+          @index_names = @free_indices + summed
+          refuse_reserved_indices
+          @outer_names = @index_names.dup
+          return
+        end
+
         if @windows.any?
           # The parameters were read before this analyzer was built -- the
           # caller had to, to know which array each window is onto -- so what
@@ -798,9 +875,23 @@ class CArray
         else
           @index_names = requireds.map(&:name)
         end
+        refuse_reserved_indices
         @outer_names = @index_names.dup
       end
 
+      # An index becomes a variable in the C this writes, alongside the
+      # kernel's own parameters, so a name C has taken already is refused
+      # here rather than by the compiler -- which would complain about a
+      # source the block's author never saw.
+      def refuse_reserved_indices
+        taken = @index_names & CGenerator::RESERVED_NAMES
+        return if taken.empty?
+        raise Unsupported.new(
+          "#{taken.map { |name| "`#{name}`" }.join(', ')} " \
+          "#{taken.size == 1 ? 'is a name' : 'are names'} the kernel's own C " \
+          "uses, so #{taken.size == 1 ? 'it cannot be an index' : 'they cannot be indices'}")
+      end
+
       # `printf` writes to the terminal from inside the loop, which is what
       # it is for: the kernel is otherwise silent until it finishes.  The
       # format has to be a literal, since C reads it at compile time.
@@ -873,6 +964,19 @@ class CArray
           if @whole_array && @array_names.include?(node.name)
             return whole_array_write(node.name, expression, node.location)
           end
+          # An index is the loop's, not the block's.  Ruby reads `i = 2` as
+          # rebinding the parameter and leaves the loop alone; the C would
+          # assign to the counter, so the loop would walk somewhere else --
+          # to cells outside the array, given a value outside its extent.
+          # The two do not mean the same thing, so this is not compiled.
+          if index_in_scope?(node.name)
+            raise Unsupported.new(
+              "`#{node.name}` is a loop index, and assigning to it here would " \
+              "move the loop rather than the value: in Ruby the same line " \
+              "rebinds the parameter and the loop runs on. Use a local of " \
+              "another name",
+              node.location)
+          end
           @local_names << node.name unless @local_names.include?(node.name)
           Assignment.new(node.name, expression, node.location)
         when Prism::CallNode
@@ -1642,6 +1746,9 @@ class CArray
           end
           @window_reach[axis] = [[@window_reach[axis][0], offset].min,
                                  [@window_reach[axis][1], offset].max]
+          own = @window_reaches[array][axis]
+          @window_reaches[array][axis] = [[own[0], offset].min,
+                                          [own[1], offset].max]
           [@outer_names[axis], offset]
         }
       end
@@ -1661,12 +1768,10 @@ class CArray
       # An index expression is `j`, `j + c` or `j - c`, where `j` is any index
       # in scope, so that the offset is a compile-time constant.
       def read_subscript (node, location)
-        if node.is_a?(Prism::LocalVariableReadNode) && index_in_scope?(node.name)
-          return [node.name, 0]
-        end
+        name = index_name(node)
+        return [name, 0] if name && index_in_scope?(name)
         if node.is_a?(Prism::CallNode) && [:+, :-].include?(node.name) &&
-           node.receiver.is_a?(Prism::LocalVariableReadNode) &&
-           index_in_scope?(node.receiver.name)
+           (receiver = index_name(node.receiver)) && index_in_scope?(receiver)
           return walked_subscript(node)
         end
         # Anything else pins the axis at a position the loop does not walk:
@@ -1741,6 +1846,20 @@ class CArray
         [receiver.name, node.name == :+ ? offset : UnaryMinus.new(offset)]
       end
 
+      # An index the block names as a parameter reads as a local variable.
+      # One named at the call site is a parameter of nothing, so Ruby reads it
+      # as a method call -- or as a local variable, where the scope the block
+      # was written in happens to have one by that name.  Both spell the same
+      # index, and which it is says nothing about what it means.
+      def index_name (node)
+        case node
+        when Prism::LocalVariableReadNode
+          node.name
+        when Prism::CallNode
+          node.name if node.receiver.nil? && node.arguments.nil? && node.block.nil?
+        end
+      end
+
       def index_in_scope? (name)
         @outer_names.include?(name) || @inner_names.include?(name)
       end

data/lib/carray/jit/c_function.rb

@@ -368,25 +368,32 @@ class CArray
         Fiddle::TYPE_USHORT    => :uint16,
         Fiddle::TYPE_INT       => :int32,
         Fiddle::TYPE_UINT      => :uint32,
-        Fiddle::TYPE_LONG      => :int64,
-        Fiddle::TYPE_LONG_LONG => :int64,
+        Fiddle::TYPE_LONG       => :int64,
+        Fiddle::TYPE_LONG_LONG  => :int64,
+        # `unsigned long` and `size_t` arrive as the same code, and
+        # `uint64_t` as the other one.
+        Fiddle::TYPE_ULONG      => :uint64,
+        Fiddle::TYPE_ULONG_LONG => :uint64,
       }.freeze
 
       # Codes Fiddle may return, mapped to what a kernel computes them in.
       # Absent means the type may be written down but holds no value a body
-      # can compute with.  `uint64_t` is absent for the reason CArray has no
-      # uint64 array: no computation type holds it without losing a bit.
+      # can compute with -- `void`, and a pointer to it.
       COMPUTATION = {
-        Fiddle::TYPE_DOUBLE    => :double,
-        Fiddle::TYPE_FLOAT     => :double,
-        Fiddle::TYPE_CHAR      => :int64,
-        Fiddle::TYPE_UCHAR     => :int64,
-        Fiddle::TYPE_SHORT     => :int64,
-        Fiddle::TYPE_USHORT    => :int64,
-        Fiddle::TYPE_INT       => :int64,
-        Fiddle::TYPE_UINT      => :int64,
-        Fiddle::TYPE_LONG      => :int64,
-        Fiddle::TYPE_LONG_LONG => :int64,
+        Fiddle::TYPE_DOUBLE     => :double,
+        Fiddle::TYPE_FLOAT      => :double,
+        Fiddle::TYPE_CHAR       => :int64,
+        Fiddle::TYPE_UCHAR      => :int64,
+        Fiddle::TYPE_SHORT      => :int64,
+        Fiddle::TYPE_USHORT     => :int64,
+        Fiddle::TYPE_INT        => :int64,
+        Fiddle::TYPE_UINT       => :int64,
+        Fiddle::TYPE_LONG       => :int64,
+        Fiddle::TYPE_LONG_LONG  => :int64,
+        # uint64 is a computation type of its own, precisely because int64
+        # cannot carry what it holds; CArray has the array to match.
+        Fiddle::TYPE_ULONG      => :uint64,
+        Fiddle::TYPE_ULONG_LONG => :uint64,
       }.freeze
 
       module_function
@@ -681,6 +688,22 @@ class CArray
                    "the signature rather than a value; the body cannot read it"
                  end)
         end
+        # A body is handed its values through the kernel's three scalar buses,
+        # which carry doubles, int64s and complexes.  A uint64 argument is the
+        # one numeric type none of them can carry whole -- that is what having
+        # its own computation type means -- so it is refused here, where the
+        # declaration is, rather than deeper down as a kernel that cannot be
+        # built.  A `uint64_t *` reaches an array of them, and a uint64_t
+        # value comes back out of a body unharmed.
+        names.zip(parameters).each do |parameter, type|
+          next if type.pointer || type.computation != :uint64
+          raise Unsupported,
+                "`#{parameter}` is declared `#{type.text}`, and a value is " \
+                "handed to a body as a double, an int64 or a complex -- a " \
+                "uint64 fits none of them without losing a bit. Take " \
+                "`#{type.text} *` and index it, or take an int64 where the " \
+                "values are small enough to be one"
+        end
         types = names.zip(parameters).reject { |_, type| type.pointer }
                      .to_h { |parameter, type| [parameter, type.computation] }
 

data/lib/carray/jit/c_generator.rb

@@ -68,6 +68,18 @@ class CArray
         "double *reals, int64_t *integers, void **functions, void **data, " \
         "char **mask_pointers, int64_t *mask_strides, int32_t *error)".freeze
 
+      # Names an index may not take, because the C it becomes is written with
+      # them: the kernel's own parameters above, and the words C keeps for
+      # itself.  A name from either list compiles to something else or to
+      # nothing, and the compiler's complaint is about a source the block's
+      # author did not write.
+      RESERVED_NAMES =
+        (SIGNATURE.scan(/\*?(\w+)[,)]/).flatten +
+         %w[auto break case char const continue default do double else enum
+            extern float for goto if inline int long register restrict return
+            short signed sizeof static struct switch typedef union unsigned
+            void volatile while]).map(&:to_sym).freeze
+
       ARGUMENTS =
         "pointers, strides, bounds, reals, integers, functions, data, " \
         "mask_pointers, mask_strides, error".freeze

data/lib/carray/jit/compiler.rb

@@ -40,7 +40,26 @@ class CArray
       # being lower was not a decision -- the flag list is the one the first
       # milestone was scaffolded with, and only the contraction flag beside
       # it was ever argued for.
-      FLAGS = ["-O3", "-fPIC", "-shared", "-ffp-contract=off"].freeze
+
+      # Every generated object exports the same fixed names -- carray_jit_kernel,
+      # carray_jit_slab, the border and error helpers -- because each one is a
+      # module of its own.  Fiddle.dlopen passes RTLD_GLOBAL, so on ELF those
+      # names all land in one flat namespace and an intra-module call resolves
+      # to the first definition loaded: a later kernel's carray_jit_slab calls
+      # an earlier kernel's carray_jit_kernel, which takes a different number
+      # of operands, reads past the pointers it was given, and the process
+      # segfaults.  -Wl,-Bsymbolic binds each object's own definitions before
+      # the global scope, which is what one object per kernel assumed all
+      # along.  Nothing else needs saying so: Mach-O binds within each dylib's
+      # own two-level namespace and PE within each DLL, so the flag is named
+      # only where it means something -- and Apple's linker rejects it
+      # outright, which would trade a Linux crash for a macOS build that never
+      # compiles at all.
+      SYMBOLIC =
+        (RbConfig::CONFIG["host_os"] =~ /darwin|mswin|mingw|cygwin/ ?
+           [] : ["-Wl,-Bsymbolic"]).freeze
+
+      FLAGS = ["-O3", "-fPIC", "-shared", "-ffp-contract=off", *SYMBOLIC].freeze
 
       # Kernels retained on disk.  Each costs about 17 KB, so the default is
       # roughly 9 MB -- far more than any real program compiles, but a bound
@@ -63,11 +82,29 @@ class CArray
         # directory for this one.
         def cache_root
           return ephemeral_directory if ephemeral?
-          ENV["CARRAY_JIT_CACHE"] ||
+          ENV["CARRAY_JIT_CACHE"] || @cache_root ||
             File.join(ENV["XDG_CACHE_HOME"] || File.join(Dir.home, ".cache"),
                       "carray-jit")
         end
 
+        # An application saying where its own kernels live, rather than
+        # sharing the one cache under the home directory.  Set it before the
+        # first kernel is compiled; kernels already loaded keep working, and
+        # what is already on disk stays where it is.  `nil` restores the
+        # default.
+        #
+        # The environment still comes first: `CARRAY_JIT_CACHE` redirects an
+        # application that names a directory here, and `CARRAY_JIT_NO_CACHE`
+        # takes the cache away, so whoever runs a program can still put it
+        # somewhere writable, or do without.
+        #
+        # The path is expanded when it is given, not when it is read: a
+        # relative one would otherwise name a different directory after the
+        # program changes its working directory.
+        def cache_root= (path)
+          @cache_root = path && File.expand_path(path)
+        end
+
         def cache_directory
           File.join(cache_root, environment_tag)
         end

data/lib/carray/jit/expression.rb

@@ -16,13 +16,24 @@ class CArray
     # goes back to CArray, which walks it and arrives at the same answer.
     class Expression
 
+      # A kernel that can divide by zero calls ca_zerodiv, which the CArray
+      # extension defines and this object does not.  ELF is content to leave
+      # the name undefined and resolve it when the object is loaded, which is
+      # what the declaration in #source_for assumes; Mach-O refuses to link at
+      # all, so on macOS every expression holding an integer `/` or `%` failed
+      # to compile and was silently handed back to CArray to walk.  The flag
+      # says to look the name up at load time, which is what Ruby builds its
+      # own extensions with and the only thing this object leaves undefined.
+      DYNAMIC_LOOKUP =
+        (RbConfig::CONFIG["host_os"] =~ /darwin/ ? ["-Wl,-undefined,dynamic_lookup"] : []).freeze
+
       # Built the way CArray's own kernels were, since that is what the answer
       # is being compared against.  The Prism front end wants the opposite of
       # this on one point -- it answers to a Ruby loop, which does not fuse a
       # multiply and an add into one rounding, so it compiles with
       # -ffp-contract=off.  Here the reference is the eager kernel, which was
       # built with whatever CArray settled on.
-      FLAGS = ["-fPIC", "-shared", *CArray::BUILD_FLAGS.split].freeze
+      FLAGS = ["-fPIC", "-shared", *CArray::BUILD_FLAGS.split, *DYNAMIC_LOOKUP].freeze
 
       C_TYPES = {
         float64: "double",  float32: "float",
@@ -37,7 +48,9 @@ class CArray
         @kernels = {}
       end
 
-      # Fills `out` and returns true, or writes nothing and returns false.
+      # Fills `out` and returns true, or returns false and leaves it to
+      # CArray.  A decline may have written part of `out` first, which is
+      # what walking it over again then settles.
       def call (plan, out)
         return false unless C_TYPES.key?(plan.data_type)
         aliased = plan.leaves.any? { |array| array.equal?(out) }
@@ -51,6 +64,25 @@ class CArray
           kernel.call(out.elements, *pointers(plan, bases))
         end
         true
+      rescue ZeroDivisionError
+        # A zero divisor is an answer, not a fault: it is what ca_zerodiv --
+        # the only thing a kernel here calls out to -- reports, and the same
+        # expression walked reaches the same place and raises the same error.
+        #
+        # CArray cannot tell the two apart, though.  It catches whatever an
+        # evaluator raises, retires it for the rest of the process and says so
+        # on stderr, which is right for an evaluator that is broken and wrong
+        # for one that has just met a zero.  So this declines instead, and
+        # CArray walks the expression and raises it there.  Anything else
+        # still reaches CArray and still retires this, which is what that net
+        # is for.
+        #
+        # What it costs: a kernel that raised where the walk does not -- over
+        # a masked zero, say -- now reads as slow rather than as wrong, since
+        # the walk answers and nobody sees the difference.  The answer is
+        # right either way, and the masked-divisor test asks the evaluator
+        # directly for that reason.
+        false
       end
 
       private

data/lib/carray/jit/kernel.rb

@@ -25,7 +25,7 @@ class CArray
                   # How far a stencil's windows reach on each axis, as
                   # [lowest, highest] per axis: what the caller walks the
                   # interior by.  Empty for a kernel that has no windows.
-                  :window_reach,
+                  :window_reach, :window_reaches,
                   # What a cell that stopped can have been raising about --
                   # the block's own `raise`s, and those of the bodies pasted
                   # into this kernel, by the code each reports.
@@ -63,6 +63,7 @@ class CArray
 
         @masked = generator.masked
         @window_reach = analyzer.window_reach
+        @window_reaches = analyzer.window_reaches
         # What `raise` in the block said, by the code the cell that raised
         # writes into the error slot.  The message does not travel: C has
         # nothing to carry it in, and it was known when this was compiled.

data/lib/carray/jit/type_assignment.rb

@@ -8,15 +8,14 @@ class CArray
     # propagates bottom-up.
     #
     # The distinction that matters is between *storage* type and *computation*
-    # type.  A Ruby block reading a float32 array gets a Ruby Float -- a
-    # double -- computes in double, and rounds back to float32 only when the
-    # value is stored.  Computing in float instead would diverge from the Ruby
-    # evaluator, so reads from any float array are typed :double here and the
-    # generator casts once, at the store.
+    # type: what an array holds, and what a kernel works on a cell of it in.
+    # They are not the same -- int8 is computed in int64 -- and the table
+    # below is what says which.
     #
-    # cmplx64 stands in the same relation to cmplx128: a cell of either is a
-    # Ruby Complex whose parts are Floats, so both are typed :complex and the
-    # narrowing happens at the store.
+    # A narrow float is computed narrow: float32 in `float` and cmplx64 in
+    # `float _Complex`, read narrow and stored narrow. That is what CArray's
+    # own kernels do, so the two agree; the Ruby evaluator, which would widen
+    # to a double, is what they both differ from. See docs/03 and docs/05.
     class TypeAssignment
 
       STORAGE_COMPUTATION_TYPES = {
@@ -60,11 +59,14 @@ class CArray
       # the reason KINDS gives: a table of names kept somewhere else keeps
       # answering after a computation type is added, and answers wrongly.
       RESULT_STORAGE_TYPES = {
-        :int64   => :int64,
-        :uint64  => :uint64,
-        :float   => :float32,
-        :double  => :float64,
-        :complex => :cmplx128,
+        :int64         => :int64,
+        :uint64        => :uint64,
+        :float         => :float32,
+        :double        => :float64,
+        # cmplx64 is to cmplx128 what float32 is to float64: the value was
+        # computed narrow, and cmplx64 holds it without widening or losing it.
+        :float_complex => :cmplx64,
+        :complex       => :cmplx128,
       }.freeze
 
       # Raises rather than falling back, because there is no type to fall back

data/lib/carray/jit/version.rb

@@ -1,5 +1,5 @@
 class CArray
   module JIT
-    VERSION = "0.1.0"
+    VERSION = "0.1.2"
   end
 end