Module:MOS: Difference between revisions

--[[

  Module for working with mosses in lua code; this serves as a "library" for

   mos-related modules and thus does not have a corresponding template.

  Functionality includes:

  - Creating scalesigs (string representations) of mosses

------------------------------- HELPER FUNCTIONS -------------------------------

 

 

-- Create a new mos. (Contains the number of large and small steps, and equave.)

-- Parse a mos from its scalesig.

local nL, ns, equave = unparsed:match("^(%d+)[Ll]%s*(%d+)[Ss]%s*(.*)$")

------------------------------- STRING FUNCTIONS -------------------------------

--[[

  Construct a string representation (scalesig) for a MOS structure.

  Scalesig is "xL ys", or "xL ys<p/q>" for nonoctave scales.

  Option to use nbsp is provided using the second param; default is no nbsp

local use_nbsp = use_nbsp or true

local suffix = ""

if not rat.eq(mos.equave, 2) then

suffix = "⟨" .. rat.as_ratio(mos.equave):lower() .. "⟩"

--[[

  Construct a longer string representation for a MOS structure.

  Scalesig is "xL ys", or "xL ys (p/q-equivalent)" for nonoctave scales.

  Option to use nbsp is provided using the second param; default is no nbsp

local use_nbsp = use_nbsp or true

local suffix = ""

if not rat.eq(mos.equave, 2) then

suffix = (use_nbsp and "&nbsp;" or " ") .. string.format("(%s-equivalent)", rat.as_ratio(mos.equave):lower())

--[[

  Given an interval as a vector of L's and s's, produce a string "iL + js",

  where i and j are the quantities for L and s.

--------------------------- MOS RELATIVES FUNCTIONS ----------------------------

-- Find the parent mos of a mos

function p.parent_mos(mos)

-- Find the two child mosses of a mos; ordered as soft and hard

function p.child_mosses(mos)

-- Find the sister of a mos

function p.sister_mos(mos)

-- Is the mos valid? It should have positive-integer values for nL and ns.

function p.is_valid_mos(mos)

return mos.nL > 0 and mos.ns > 0

--[[

  Find the brightest (true-mos) mode of a mos, as a string of L's and s's.

  Calculation is based on the definition of a Christoffel word, as the closest

  integer approximation to line y = #s/#L*x.

--[[

  Given a mos, return a mode based on how it's ranked by modal brightness.

  Ordering here is based on the number of bright gens going DOWN PER PERIOD:

  0 is the brightest mode, 1 is 2nd brightest, etc...

]]--

function p.mode_from_mos(mos, bright_gens_down)

--[[

  List all unique rotations for a mode. Order of modes is by rotation.

  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

  modes, but if there is a substring of length p that repeats within the mode

  (where p divides s with remainder = 0), then there will be p modes. It's also

  possible to have only one mode, but this can only happen if there is only one

  step size, meaning it's a unary scale (only one step size).

if not p.find_item_in_table(rotations, current_mode) then

--[[

  Rotate a mode by shifting the step sequence to the left. Negative values

  shift it to the right. Helper function for mode_from_mos().

--[[

  Convert a single mode (as a string) into a step matrix. This is a listing of

  every interval's step vector in the mode.

--[[

  Given a mos, produce every step matrix for every mode. Modes are listed in

  order of brightness.

--[[

  Given a single mode (as a string), produce the step matrices for each  

  rotation of that mode. Modes are listed in order of rotation.

--[[

  Given an input mos, produce its modal union.

  This is a listing of every interval's large and small sizes.

--------------- INTERVAL FUNCTIONS FOR PERFECTABLE INTERVALS -------------------

------------------ (IE, GENERATORS AND PERIOD INTERVALS) -----------------------

--[[

  Compute the bright gen as a vector of L's and s's.

  Bright gen has two sizes: perfect (large) and diminished (small). The size

  given by this function is the large size.

--[[

  Compute the dark gen as a vector of L's and s's.

  Dark gen has two sizes: augmented (large) and perfect (small). The size given

  by this function is the small size and is equal to the period complement of the

  bright gen.

-- Compute the period as a vector of L's and s's. Period intervals only have one size: perfect.

--[[

  Compute the equave as a vector of L's and s's.

  Equave intervals only have one size: perfect. Equave and period intervals are

  the same for single-period mosses.

------------------ INTERVAL FUNCTIONS FOR SIMPLE INTERVALS ---------------------

--[[

  Compute 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

  not need a mos as input. It's basically a zero vector.

  The unison only has one size: perfect.

--[[

  Compute 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".

-- Compute the vector for an augmented step. It's a large step plus a chroma.

-- Compute the vector for a single large step.

-- Compute the vector for a single small step.

-- Compute the vector for a diminished step. It's a small step minus a chroma.

--[[

  Compute an arbitrary mos interval as a vector of L's and s's.

  The step_count param is the number of mossteps in the interval. EG, in 5L 2s,

  the large 2-mosstep is "LL", so the corresponding vector has L=2, s=0.

  Mossteps larger than the equave (eg, the minor 9th in non-xen music theory)

  The size_offset denotes whether the interval is the large size (0) or the

   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.

--[[

  Compute an arbitrary mos interval (as a string of steps) as a vector of L's

  and s's. This also serves as a helper function for p.interval_from_mos().

  Sequences of steps can be entered, where each step is one of five sizes:

  - L: large step.

  - s: small step.

  - c: a chroma; the difference between a large and small step.

  - A: an augmented step; a large step plus a chroma.

  - d: a diminished step, or diesis; a small step minus a chroma.

-- Given a mos, compute the number of steps in its equave (L's plus s's).

--[[

  Given a vector representing an interval, compute the number of mossteps it

  corresponds to. Knowledge of the corresponding mos is not needed. Intervals

  can be negative, resulting in a negative output.

--[[

  Given a vector representing an interval, compute the number of chromas it was

  raised or lowered by from its large size (for non-period intervals) or its

  perfect size (for period/root/equave intervals). This requires the mos as

  input.

  If the number of chromas from a small (EG minor) interval is desired, then

  using the param size_offset can be used: 0 for chromas from large size, -1

  for chromas from small size. This can exceed the range [-1, 0] if needed.

 

  E.G., a diminished 2-diastep (dim. 3rd) has the vector {0,2}. It's reached by

  either lowering the major 2-step by 2 chromas, or lowering the minor 2-step

  by 1 chroma.

----------------------- INTERVAL ARITHMETIC FUNCTIONS --------------------------

-- Repeatedly add the same interval to itself.

---------------------- INTERVAL MANIPULATION FUNCTIONS -------------------------

  Given an interval vector and a mos, find its period complement. This is the

  interval to add to produce the period.

]]--

--[[

  Given an interval vector and a mos, find its equave complement. This is the

  interval to add to produce the equave.

--[[

  Given an interval vector and a mos, period-reduce it. This works like

  modular arithmetic, so passing a negative interval returns a positive one.

]]--

--[[

  Given an interval vector and a mos, equave-reduce it. This works like

  modular arithmetic, so passing a negative interval returns a positive one.

--[[

  Intervals usually denote distances between two scale degrees and should be

  positive values. Normalizing makes a negative interval positive again.

--[[

  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

  ratios to be entered. (The rational module isn't suitable since it simplifies

  ratios.)

function p.mos_to_et(mos, step_ratio, suffix)

--[[

  Given a mos and a step ratio, return the number of et-steps for its bright

  generator.

function p.mos_to_et_suffix(mos)

function p.mos_to_et_as_string(mos, step_ratio, suffix)

local et_mos = p.mos_to_et(mos, step_ratio, suffix)

function p.bright_gen_to_et_steps_as_string(mos, step_ratio, suffix)

return p.interval_to_et_steps_as_string(p.bright_gen(mos), mos, step_ratio, suffix)

function p.dark_gen_to_et_steps_as_string(mos, step_ratio, suffix)

return p.interval_to_et_steps_as_string(p.dark_gen(mos), mos, step_ratio, suffix)

function p.period_to_et_steps_as_string(mos, step_ratio, suffix)

return p.interval_to_et_steps_as_string(p.period(mos), mos, step_ratio, suffix)

function p.equave_to_et_steps_as_string(mos, step_ratio, suffix)

return p.interval_to_et_steps_as_string(p.equave(mos), mos, step_ratio, suffix)

function p.interval_to_et_steps_as_string(interval, mos, step_ratio, suffix)

local mos_et = p.mos_to_et(mos, step_ratio, suffix)

--[[

  Given a mos and a step ratio, return the number of cents for its period.

 

  The period is the interval at which the step pattern repeats, so no step

  ratio is needed.

--[[

  Given a mos and a step ratio, return the number of cents for its equave.

  The period is the interval at which the step pattern repeats, and the equave

  is a multiple of that (at least for multi-period mosses), so no step ratio is

  needed.

local input_mos = p.new(5,2)

return p.mos_to_et_as_string(input_mos, step_ratio) .. "\n"

.. p.interval_to_et_steps_as_string(interval_vector, input_mos, step_ratio)

--return p.mos_to_et(p.new(5,2), {2,1})