Xenharmonic Wiki

Module:MOS: Difference between revisions

← Older edit
Ganaram inukshuk (talk | contribs)
autopatrolled, emailconfirmed
6,211 edits
added is_root_mos, under the reasoning that this came up enough times to justify adding it
Ganaram inukshuk (talk | contribs)
autopatrolled, emailconfirmed
6,211 edits
mNo edit summary
 
(8 intermediate revisions by 2 users not shown)
Line 1: Line 1:
-- Module for working with mosses in lua code; this serves as a "library" for
-- This module follows [[User:Ganaram inukshuk/Provisional style guide for Lua]]
-- mos-related modules and thus does not have a corresponding template.
local et    = require("Module:ET")
local rat  = require("Module:Rational")
local utils = require("Module:Utils")


-- Following style guide: https://en.xen.wiki/w/User:Ganaram_inukshuk/Provisional_style_guide_for_Lua#Lua_style
 
-- Functionality includes:
-- - Creating/parsing mosses from string representations (scalesigs, xL ys)
-- - Creating scalesigs (string representations) of mosses
-- - Finding relatives of mosses or applying certain operations on them
-- - Finding certain modes of a mos
-- - Finding generators for a mos
-- - Producing vectors for simple mos intervals
-- - Interval arithmetic, in the form of adding vectors of L's and s's, and
--  period/equave-reducing intervals
-- - Finding equal tunings for mosses
-- - Producing intervals of mosses as steps of an equal tuning, as a quantity of
--  steps (EG, for 7\12, this is 7) or as a string (EG, 7\12 as a string).
local rat = require("Module:Rational")
local utils = require("Module:Utils")
local et = require("Module:ET")
local p = {}
local p = {}
-- Naming scheme for function names:
-- - Functions related to mosses don't have any special names.
-- - Functions related to a mos's modes generally end with "mode".
-- - Functions related to a mos's generators, equave, or period contain the
--  corresponding interval as part of its name.
-- - Functions related to intervals generally begin with "interval".
-- - Interval complement/reduce functions end with "complement" and "reduce".
-- - Functions that produce strings generally have the phrase "as string".
-- - Functions that "count" something generally end with "count".
-- - If a function requires an interval and mos as input, the interval(s) come
--  after the mos.
-- - Functions that have to do with equal tunings will have "et" in its name.


--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
------------------------------- HELPER FUNCTIONS -------------------------------
----------------------------- MOS-CREATING FUNCTIONS ---------------------------
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------


function p.find_item_in_table(table, item)
-- Create a new mos as a table containing the counts for large and small steps,
local item_found = false
-- plus the equave.
for i = 1, #table do
if table[i] == item then
item_found = true
break
end
end
return item_found
end
 
--------------------------------------------------------------------------------
-------------------------------- BASE FUNCTIONS --------------------------------
--------------------------------------------------------------------------------
 
-- Create a new mos. (Contains the number of large and small steps, and equave.)
function p.new(nL, ns, equave)
function p.new(nL, ns, equave)
local nL = nL or 5
local nL = nL or 5
Line 64: Line 20:
end
end


-- Parse a mos from its scalesig.
-- Parse a mos from its scalesig "xL ys<p/q>" or "xL ys (p/q-equivalent)".
-- If no equave "p/q" is provided, it's assumed to be 2/1-equivalent.
function p.parse(unparsed)
function p.parse(unparsed)
local nL, ns, equave = unparsed:match("^(%d+)[Ll]%s*(%d+)[Ss]%s*(.*)$")
local nL, ns, equave = unparsed:match("^(%d+)[Ll].-(%d+)[Ss]%s*(.*)$")
nL = tonumber(nL)
nL = tonumber(nL)
ns = tonumber(ns)
ns = tonumber(ns)
Line 79: Line 36:


--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
----------------------------- CHECK-ING FUNCTIONS ------------------------------
---------------------- VALIDATION AND CHECKING FUNCTIONS -----------------------
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------


Line 106: Line 63:
-- Degenerate mosses (nL 0s or 0L ns) produce a string for its corresponding
-- Degenerate mosses (nL 0s or 0L ns) produce a string for its corresponding
-- et (n-ed-p/q).
-- et (n-ed-p/q).
-- Option to use nbsp is provided using the second param; default is nbsp
-- Option to use nbsp is provided using the second param; default is nbsp.
function p.as_string(mos, use_nbsp)
function p.as_string(mos, use_nbsp)
if p.is_valid(mos) then
if p.is_valid(mos) then
Line 114: Line 71:
suffix = "⟨" .. rat.as_ratio(mos.equave):lower() .. "⟩"
suffix = "⟨" .. rat.as_ratio(mos.equave):lower() .. "⟩"
end
end
return "" .. mos.nL .. "L" .. (use_nbsp and "&nbsp;" or " ") .. mos.ns .. "s" .. suffix
return mos.nL .. "L" .. (use_nbsp and "&nbsp;" or " ") .. mos.ns .. "s" .. suffix
else
else
return "" .. math.max(mos.nL, mos.ns) .. p.et_suffix(mos)
return math.max(mos.nL, mos.ns) .. p.et_suffix(mos)
end
end
end
end
Line 124: Line 81:
-- Degenerate mosses (nL 0s or 0L ns) produce a string for its corresponding
-- Degenerate mosses (nL 0s or 0L ns) produce a string for its corresponding
-- et (n-ed-p/q).
-- et (n-ed-p/q).
-- Option to use nbsp is provided using the second param; default is nbsp
-- Option to use nbsp is provided using the second param; default is nbsp.
function p.as_long_string(mos, use_nbsp)
function p.as_long_string(mos, use_nbsp)
if p.is_valid(mos) then
if p.is_valid(mos) then
Line 132: Line 89:
suffix = (use_nbsp and "&nbsp;" or " ") .. string.format("(%s-equivalent)", rat.as_ratio(mos.equave):lower())
suffix = (use_nbsp and "&nbsp;" or " ") .. string.format("(%s-equivalent)", rat.as_ratio(mos.equave):lower())
end
end
return "" .. mos.nL .. "L" .. (use_nbsp and "&nbsp;" or " ") .. mos.ns .. "s" .. suffix
return mos.nL .. "L" .. (use_nbsp and "&nbsp;" or " ") .. mos.ns .. "s" .. suffix
else
else
return "" .. math.max(mos.nL, mos.ns) .. p.et_suffix(mos)
return math.max(mos.nL, mos.ns) .. p.et_suffix(mos)
end
end
end
end
Line 147: Line 104:
return string.format("[[%s]]", link)
return string.format("[[%s]]", link)
else
else
return string.format("[[%s | %s]]", link, text)
return string.format("[[%s|%s]]", link, text)
end
end
end
end
Line 207: Line 164:
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------


-- Find the parent mos of a mos. May return invalid mosses (nL 0s), meant
-- Find the parent mos of a mos. May return invalid mosses (nL 0s), meant to
-- to represent equal divisions of the octave (or arbitrary equave).
-- represent equal divisions of the octave (or arbitrary equave).
function p.parent(mos)
function p.parent(mos)
return p.new(math.min(mos.nL, mos.ns), math.abs(mos.nL-mos.ns), mos.equave)
return p.new(math.min(mos.nL, mos.ns), math.abs(mos.nL-mos.ns), mos.equave)
Line 321: Line 278:
end
end


-- List all unique rotations for a mode, by order of leftward shifts.
-- List all unique rotations for a mode, by order of leftward shifts. Order by
-- rotation will usually give a different order compared to order by brightness,
-- but this is expected if the order isn't by brightness (EG, modmosses).
-- Note: there will always be s/p modes, where s is the number of steps in the
-- Note: there will always be s/p modes, where s is the number of steps in the
-- entered mode, and p is the period of repetition. At most, there will be s
-- entered mode, and p is the period of repetition. At most, there will be s
Line 331: Line 290:
local current_mode = mode_string
local current_mode = mode_string
for i = 1, #mode_string do
for i = 1, #mode_string do
if not p.find_item_in_table(rotations, current_mode) then
if not utils.table_contains(rotations, current_mode) then
table.insert(rotations, current_mode)
table.insert(rotations, current_mode)
end
end
Line 421: Line 380:


--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
--------------- INTERVAL FUNCTIONS FOR PERFECTABLE INTERVALS -------------------
--------------- FUNCTIONS FOR GENERATOR AND PERIOD INTERVALS -------------------
------------------ (IE, GENERATORS AND PERIOD INTERVALS) -----------------------
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------


-- Compute the bright gen as a vector of L's and s's.
-- Compute the bright gen as a vector of L's and s's. Since all mosstep
-- Bright gen has two sizes: perfect (large) and diminished (small). The size
-- intervals (excluding the root and period) have two sizes, this returns the
-- given by this function is the large size.
-- large/perfect size.
function p.bright_gen(mos)
function p.bright_gen(mos)
local nL = mos.nL
local nL = mos.nL
Line 458: Line 416:
end
end


-- Compute the dark gen as a vector of L's and s's.
-- Compute the dark gen as a vector of L's and s's. Since all mosstep
-- Dark gen has two sizes: augmented (large) and perfect (small). The size given
-- intervals (excluding the root and period) have two sizes, this returns the
-- by this function is the small size and is equal to the period complement of the
-- small/perfect size.
-- bright gen.
function p.dark_gen(mos)
function p.dark_gen(mos)
local bright_gen = p.bright_gen(mos)
local bright_gen = p.bright_gen(mos)
Line 467: Line 424:
end
end


-- Compute the period as a vector of L's and s's. Period intervals only have one size: perfect.
-- Compute the period as a vector of L's and s's.
-- Period intervals as mossteps only appear as one size.
function p.period(mos)  
function p.period(mos)  
local gcd = utils._gcd(mos.nL, mos.ns)
local gcd = utils._gcd(mos.nL, mos.ns)
Line 477: Line 435:


-- Compute the equave as a vector of L's and s's.
-- Compute the equave as a vector of L's and s's.
-- Equave intervals only have one size: perfect. Equave and period intervals are
-- Equaves as mossteps only appear as one size. For a single-period mos, this
-- the same for single-period mosses.
-- is the same as p.period().
function p.equave(mos)  
function p.equave(mos)  
return {
return {
Line 487: Line 445:


--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
------------------ INTERVAL FUNCTIONS FOR SIMPLE INTERVALS ---------------------
------------------- FUNCTIONS FOR SINGLE-STEP INTERVALS ------------------------
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------


-- Compute the unison as a vector of L's and s's.
-- Return the unison as a vector of L's and s's.
-- The unison is denoted by moving up from the root by zero steps, and thus does
-- The unison is denoted by moving up from the root by zero steps, and thus does
-- not need a mos as input. It's basically a zero vector.
-- not need a mos as input. It's basically a zero vector.
Line 498: Line 456:
end
end


-- Compute the vector for a single chroma. It's a large step minus a small step.
-- Return the vector for a single chroma. It's a large step minus a small step.
-- Adding or subtracting any interval by this interval changes its "size".
-- Adding or subtracting any interval by this interval changes its "size".
function p.chroma()
function p.chroma()
Line 504: Line 462:
end
end


-- Compute the vector for an augmented step. It's a large step plus a chroma.
-- Return the vector for an augmented step. It's a large step plus a chroma.
function p.augmented_step()
function p.augmented_step()
return { ["L"] = 2, ["s"] = -1 }
return { ["L"] = 2, ["s"] = -1 }
end
end


-- Compute the vector for a single large step.
-- Return the vector for a single large step.
function p.large_step()
function p.large_step()
return { ["L"] = 1, ["s"] = 0 }
return { ["L"] = 1, ["s"] = 0 }
end
end


-- Compute the vector for a single small step.
-- Return the vector for a single small step.
function p.small_step()
function p.small_step()
return { ["L"] = 0, ["s"] = 1 }
return { ["L"] = 0, ["s"] = 1 }
end
end


-- Compute the vector for a diminished step. It's a small step minus a chroma.
-- Return the vector for a diminished step. It's a small step minus a chroma.
function p.diminished_step()
function p.diminished_step()
return { ["L"] = -1, ["s"] = 2 }
return { ["L"] = -1, ["s"] = 2 }
Line 533: Line 491:
end
end


-- Compute an arbitrary mos interval as a vector of L's and s's.
-- Compute an arbitrary mos interval as a vector of L's and s's. Params:
-- The step_count param is the number of mossteps in the interval. EG, in 5L 2s,
-- - step_count: the number of steps subtended by the mosstep.
-- the large 2-mosstep is "LL", so the corresponding vector has L=2, s=0.
-- - size_offset: denotes whether to return the large size (0) or the small
-- Mossteps larger than the equave (eg, the minor 9th in non-xen music theory)
--   size (-1) (or if this is a period interval, the diminished size). Values
-- are allowed.
--   other than 0 or 1 represent alterations by multiple chromas, such as
-- The size_offset denotes whether the interval is the large size (0) or the
--   augmented (1) or diminished (-2).
-- small size (-1). This can exceed the range of [-1, 0] to represent intervals
-- raised/lowered by multiple chromas (augmented, diminished, etc).
-- Note that for period intervals (eg, the root and equave), there is only one
-- size (0 = perfect), so -1 is diminished and 1 is augmented.
-- E.G., a perfect 4-diastep (perf. 5th) is 4 steps. Since it's the large size,
-- the offset is 0, but to get the diminished 5th, the offset should be -1.
function p.interval_from_mos(mos, step_count, size_offset)
function p.interval_from_mos(mos, step_count, size_offset)
local size_offset = size_offset or 0 -- Optional param; defaults to large size
local size_offset = size_offset or 0 -- Optional param; defaults to large size
Line 591: Line 543:
------------------------------- COUNT FUNCTIONS --------------------------------
------------------------------- COUNT FUNCTIONS --------------------------------
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
-- Given a mos, return the number of steps.
function p.step_count(mos)
return mos.nL + mos.ns
end


-- Given a mos, compute the number of steps in its bright gen (L's plus s's).
-- Given a mos, compute the number of steps in its bright gen (L's plus s's).
Line 608: Line 565:
end
end


-- Given a mos, compute the number of steps in its equave (L's plus s's).
-- TODO: deprecate this since "equave_step_count" is redundant and longer than
-- "step count".
function p.equave_step_count(mos)
function p.equave_step_count(mos)
return mos.nL + mos.ns
return mos.nL + mos.ns
Line 629: Line 587:
-- perfect size (for period/root/equave intervals). This requires the mos as
-- perfect size (for period/root/equave intervals). This requires the mos as
-- input.
-- input.
-- If the number of chromas from a small (EG minor) interval is desired, then
-- size_offset denotes whether to count chromas from the large size; changing
-- using the param size_offset can be used: 0 for chromas from large size, -1
-- this to -1 counts chromas from the small size. Like size_offset for
-- for chromas from small size. This can exceed the range [-1, 0] if needed.
-- interval_from_mos, this can be used to denote altered mossteps (augmented,
-- E.G., a diminished 2-diastep (dim. 3rd) has the vector {0,2}. It's reached by
-- diminished, etc).
-- either lowering the major 2-step by 2 chromas, or lowering the minor 2-step
-- by 1 chroma.
function p.interval_chroma_count(interval, mos, size_offset)
function p.interval_chroma_count(interval, mos, size_offset)
local size_offset = size_offset or 0 -- Default of 0.
local size_offset = size_offset or 0 -- Default of 0.
Line 644: Line 600:


--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
----------------------- INTERVAL ARITHMETIC FUNCTIONS --------------------------
--------------- INTERVAL ARITHMETIC AND MANIPULATION FUNCTIONS -----------------
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------


Line 663: Line 619:
end
end


-- Repeatedly add the same interval to itself.
-- Stack an interval, or repeatedly add the same interval to itself.
function p.interval_mul(interval, amt)
function p.interval_mul(interval, amt)
return {  
return {  
Line 677: Line 633:
interval_1["s"] == interval_2["s"]
interval_1["s"] == interval_2["s"]
end
end
--------------------------------------------------------------------------------
---------------------- INTERVAL MANIPULATION FUNCTIONS -------------------------
--------------------------------------------------------------------------------


-- Given an interval vector and a mos, find its period complement. This is the
-- Given an interval vector and a mos, find its period complement. This is the
Line 734: Line 687:
---------------------------- EQUAL-TUNING FUNCTIONS ----------------------------
---------------------------- EQUAL-TUNING FUNCTIONS ----------------------------
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
-- Given a mos and a step ratio, return an equal tuning (or equal division).
-- Given a mos and a step ratio, return an equal tuning (or equal division).
-- The step ratio is entered as a 2-element array to allow non-simplified
-- The step ratio is entered as a 2-element array to allow non-simplified
Retrieved from "https://en.xen.wiki/w/Module:MOS"