Module:ChordVoicings

Documentation for this module may be created at Module:ChordVoicings/doc

-- Module:ChordVoicings (hardened against CPU limit / signal 24)
-- Usage: {{ChordVoicingTable|rchord=4:5:6:7}}

local p = {}

-- ---------- utilities ----------
local function split_enum(s)
    local t = {}
    for num in string.gmatch(s or "", "%d+") do
        t[#t+1] = tonumber(num)
    end
    return t
end

local function gcd(a,b)
    while b ~= 0 do a, b = a % b, b end
    return math.abs(a)
end
local function gcd_list(t)
    local g = t[1]
    for i=2,#t do g = gcd(g, t[i]) end
    return g
end

local function odd_part(n)
    while n % 2 == 0 do n = math.floor(n/2) end
    return n
end

local function to_str(t)
    local parts = {}
    for i=1,#t do parts[i]=tostring(t[i]) end
    return table.concat(parts, ":")
end
local function sort_key(t)
    local parts = {}
    for i=1,#t do parts[i]=string.format("%03d", t[i]) end
    return table.concat(parts, "-")
end

local function span_ratio(t)
    local mn, mx = t[1], t[1]
    for i=2,#t do
        if t[i]<mn then mn=t[i] end
        if t[i]>mx then mx=t[i] end
    end
    return mx/mn
end

-- memoized reduction
local reduce_cache = {}
local function key_of(t) return sort_key(t) end
local function clone(t)
    local u = {}
    for i=1,#t do u[i]=t[i] end
    return u
end
local function reduce_irreducible(t)
    local k = key_of(t)
    local cached = reduce_cache[k]
    if cached then return cached end
    local g = gcd_list(t)
    local u
    if g>1 then
        u = {}
        for i=1,#t do u[i]=math.floor(t[i]/g) end
    else
        u = clone(t)
    end
    reduce_cache[k] = u
    return u
end

-- two-octave rotation step
local function rot2_once(t)
    local n = #t
    local u = {}
    for i=2,n do u[#u+1] = t[i] end
    u[#u+1] = t[1]*4
    return reduce_irreducible(u)
end

local function toodds(enum)
    local odds = {}
    for i=1,#enum do odds[i] = odd_part(enum[i]) end
    return odds
end

local function unique_in_order(t)
    local seen, out = {}, {}
    for _,x in ipairs(t) do if not seen[x] then seen[x]=true; out[#out+1]=x end end
    return out
end

-- subsets
local function all_nonempty_subsets(arr)
    local res = {}
    local function rec(i, cur)
        if i > #arr then
            if #cur > 0 then
                local add = {}
                for k=1,#cur do add[k]=cur[k] end
                res[#res+1] = add
            end
            return
        end
        rec(i+1, cur)                -- exclude
        cur[#cur+1] = arr[i]; rec(i+1, cur); cur[#cur] = nil -- include
    end
    rec(1, {})
    return res
end

local function subset_labels(nonroot_odds)
    local nums = {}
    for i,x in ipairs(nonroot_odds) do nums[i]=x end
    table.sort(nums)

    local labels = {}
    labels[#labels+1] = { text="Root", set={} }

    local subsets = all_nonempty_subsets(nums)
    table.sort(subsets, function(a,b)
        if #a ~= #b then return #a < #b end
        for i=1,math.min(#a,#b) do
            if a[i] ~= b[i] then return a[i] < b[i] end
        end
        return #a < #b
    end)
    for _,set in ipairs(subsets) do
        local parts={}
        for i,od in ipairs(set) do parts[i] = "'" .. tostring(od) end
        labels[#labels+1] = { text=table.concat(parts, ""), set=set }
    end
    return labels
end

local function apply_octaves(enum, odds, chosen_set)
    local out = {}
    for i=1,#enum do
        local v = enum[i]
        if chosen_set[odds[i]] then v = v * 2 end
        out[i] = v
    end
    return out
end

local function italicize(s) return "''" .. s .. "''" end
local function bold_italic(s) return "'''''" .. s .. "'''''" end

-- ---------- hardened rotation cycle with cap ----------
local function build_rotation_map(start_vec)
    local map = {}
    local seen = {}

    local v = reduce_irreducible(start_vec)
    local steps, MAX = 0, 512   -- hard cap to avoid CPU overruns

    while true do
        local fodd = odd_part(v[1])
        if not map[fodd] then map[fodd] = v end

        local sig = key_of(v)
        if seen[sig] then break end
        seen[sig] = true

        local nextv = rot2_once(v)
        steps = steps + 1
        if steps > MAX then break end

        v = nextv
    end
    return map
end

-- ---------- main render ----------
function p.render(frame)
    local args = frame.args or frame:getParent().args
    local rchord_str = (args.rchord or args[1] or ""):gsub("%s+", "")
    if rchord_str == "" then
        return "<strong class=\"error\">Missing parameter: rchord</strong>"
    end

    local width = args.width or "120px"
    local title = args.title or "Voicings and rotations around two octaves"
    local cls   = args.class or "wikitable sortable"

    -- parse & sanity
    local enum = split_enum(rchord_str)
    if #enum < 3 then
        return "<strong class=\"error\">rchord must have at least 3 integers</strong>"
    end
    -- optional global guard for pathological inputs
    if #enum > 7 then
        return "<strong class=\"error\">rchord too large for on-wiki render (max 7 terms)</strong>"
    end

    local odds = toodds(enum)
    local root_odd = odd_part(enum[1])
    local odd_rows = unique_in_order(odds)

    -- columns: Root + subsets of non-root odds
    local nonroot_odds_unique = {}
    for _,o in ipairs(odd_rows) do
        if o ~= root_odd then nonroot_odds_unique[#nonroot_odds_unique+1] = o end
    end
    local col_specs = subset_labels(nonroot_odds_unique) -- {text,set}

    -- trivial case: if there are no non-root odds, only the Root column exists
    if #col_specs == 1 then
        local only = reduce_irreducible(enum)
        local out = {}
        out[#out+1] = "== " .. title .. " =="
        out[#out+1] = string.format('{| class="%s" style="text-align:center;"', cls)
        out[#out+1] = "|+"
        out[#out+1] = string.format('! style="width:%s;" {{diagonal split header|Rotation|Voicing}}', width)
        out[#out+1] = string.format('! style="width:%s;" | Root', width)

        for _,rowodd in ipairs(odd_rows) do
            out[#out+1] = "|-"
            out[#out+1] = string.format('! style="width:%s;" | On %s', width, tostring(rowodd))

            local rotated_map = build_rotation_map(enum)
            local r = rotated_map[rowodd] or reduce_irreducible(enum)
            local disp = to_str(r)
            local shown = (rowodd == root_odd) and bold_italic(disp) or disp
            out[#out+1] = string.format('| data-sort-value="%s" | %s', sort_key(r), shown)
        end
        out[#out+1] = "|}"
        out[#out+1] = "Enumerations in italics map to an existing octave-reduced rotation."
        return table.concat(out, "\n")
    end

    -- header
    local out = {}
    out[#out+1] = "== " .. title .. " =="
    out[#out+1] = string.format('{| class="%s" style="text-align:center;"', cls)
    out[#out+1] = "|+"
    out[#out+1] = string.format('! style="width:%s;" {{diagonal split header|Rotation|Voicing}}', width)
    for _,spec in ipairs(col_specs) do
        out[#out+1] = string.format('! style="width:%s;" | %s', width, spec.text)
    end

    -- Precompute one rotation map per column (voicing)
    local rotation_maps = {}
    for c, spec in ipairs(col_specs) do
        local chosen = {}
        for _,od in ipairs(spec.set) do chosen[od] = true end
        local base_voicing = apply_octaves(enum, odds, chosen)
        rotation_maps[c] = build_rotation_map(base_voicing)
    end

    -- Emit rows
    for _,rowodd in ipairs(odd_rows) do
        out[#out+1] = "|-"
        out[#out+1] = string.format('! style="width:%s;" | On %s', width, tostring(rowodd))

        for c, spec in ipairs(col_specs) do
            local rotated = rotation_maps[c][rowodd]
            if not rotated then
                -- fallback (rare): use reduced base voicing
                local chosen = {}
                for _,od in ipairs(spec.set) do chosen[od] = true end
                rotated = reduce_irreducible(apply_octaves(enum, odds, chosen))
            end

            local disp = to_str(rotated)
            local sortv = sort_key(rotated)
            local shown
            local is_two_octaves = (span_ratio(rotated) >= 4.0)

            if rowodd == root_odd and #spec.set == 0 then
                shown = bold_italic(disp)
            elseif not is_two_octaves then
                shown = italicize(disp)
            else
                shown = disp
            end

            out[#out+1] = string.format('| data-sort-value="%s" | %s', sortv, shown)
        end
    end

    out[#out+1] = "|}"
    out[#out+1] = "Enumerations in italics map to an existing octave-reduced rotation."
    return table.concat(out, "\n")
end

return p