Lua: Create Connections with create_connection

Description

In Lua context, modalys.create_connection creates Modalys connections from a parameter table. The same function is also available as create_connection, make_connection, and modalys.make_connection.

Lua Syntax

local connection = create_connection{
    kind = "pluck",
    where1 = stringAccess,
    where2 = plectrumAccess,
    breakingforce = 100,
    weight = 0.7,
    name = "Pluck"
}

Supported Kinds

The implementation currently handles these connection kinds:

• force
• speed
• position
• strike
• pluck
• felt
• bow
• adhere
• spring
• hole
• viscous-damping
• reed
• normalised-valve
• mono-fingerboard
• bi-fingerboard
• valve
• leaky-valve
• normalised-leaky-valve
• induction
• labium

Parameter aliases are normalized before dispatch, so common spellings using hyphens or underscores are accepted.

Connection-Specific Parameters

force

• access or where: required target access.
• input: optional driving controller. If omitted, a dynamic controller is created.
• initialforce: initial force value for the generated controller. Default is 0.
• weight: weight value or controller. Default is 1.

local force = create_connection{ kind="force", where=access, initialforce=0, weight=1 }

speed

• access or where: required target access.
• input: optional driving controller. If omitted, a dynamic controller is created.
• initialspeed: initial speed value for the generated controller. Default is 0.
• weight: weight value or controller. Default is 1.

local speed = create_connection{ kind="speed", where=access, initialspeed=0, weight=1 }

position

• access or where: required target access.
• input: optional driving controller. If omitted, a dynamic controller is created.
• initialposition: initial position value for the generated controller. Default is 1.
• weight: weight value or controller. Default is 1.

local position = create_connection{ kind="position", where=access, initialposition=1, weight=1 }

strike

For bilateral strike:

• object1access or where1: required first access.
• object2access or where2: required second access.
• object1initialposition: default 0.
• object2initialposition: default 0.
• weight: weight value or controller. Default is 1.

For unilateral strike:

• objectaccess or where: required access.
• initialposition: default 0.
• weight: weight value or controller. Default is 1.

local bilateral = create_connection{
    kind = "strike",
    where1 = objectAccess,
    where2 = hammerAccess,
    object1initialposition = 0,
    object2initialposition = 0,
    weight = 0.8
}

local unilateral = create_connection{
    kind = "strike",
    where = objectAccess,
    initialposition = 0,
    weight = 0.8
}

pluck

• plectrumaccess or where1: required plectrum access.
• objectaccess or where2: required object access.
• plectruminitialposition: default 0.
• objectinitialposition: default 0.
• breakingforce: value or controller. Default is 1.
• weight: weight value or controller. Default is 1.

local pluck = create_connection{
    kind = "pluck",
    where1 = plectrumAccess,
    where2 = stringAccess,
    breakingforce = 100,
    weight = 0.7
}

felt

• hammeraccess or where1: required hammer access.
• objectaccess or where2: required object access.
• hammerinitialposition or initialposition1: default 0.
• objectinitialposition or initialposition2: default 0.1.
• thickness: value or controller. Default is 0.001.
• f0: value or controller. Default is 1e9.
• alpha: value or controller. Default is 3.
• epsilon: value or controller. Default is 0.5.
• tau: value or controller. Default is 0.00001.
• weight: weight value or controller. Default is 1.

local felt = create_connection{
    kind = "felt",
    where1 = hammerAccess,
    where2 = objectAccess,
    thickness = 0.01,
    f0 = 1000,
    alpha = 2.5,
    epsilon = 0.55,
    tau = 1e-7,
    weight = 0.8
}

bow

• bowvaccess: required bow vertical access.
• bowhaccess: required bow horizontal access.
• objectvaccess: required object vertical access.
• objecthaccess: required object horizontal access.
• bowinitialvposition: default 0.1.
• objectinitialvposition: default 0.
• rosin: value table or controller. Default is { 2, 10, 5, 4 }.
• weight: weight value or controller. Default is 1.

local bow = create_connection{
    kind = "bow",
    bowvaccess = bowVerticalAccess,
    bowhaccess = bowHorizontalAccess,
    objectvaccess = stringVerticalAccess,
    objecthaccess = stringHorizontalAccess,
    bowinitialvposition = 0.1,
    objectinitialvposition = 0,
    rosin = { 2, 10, 5, 4 },
    weight = 1
}

adhere

For unilateral adhere:

• access, objectaccess, or where: required access.
• weight: weight value or controller. Default is 1.

For bilateral adhere:

• access1, object1access, or where1: required first access.
• access2, object2access, or where2: required second access.
• weight: weight value or controller. Default is 1.

local unilateral = create_connection{ kind="adhere", where=access, weight=0.3 }
local bilateral = create_connection{ kind="adhere", where1=access1, where2=access2, weight=0.7 }

spring

• where1: required first access.
• where2: required second access.
• stiffness: value or controller. Default is 15000.
• freqloss: value or controller. Default is 10.
• constloss: value or controller. Default is 10.
• weight: weight value or controller. Default is 1.

local spring = create_connection{
    kind = "spring",
    where1 = access1,
    where2 = access2,
    stiffness = 10000,
    freqloss = 10,
    constloss = 10,
    weight = 0.9
}

hole

• access or where: required tube access.
• radius: required radius value or controller.
• noise: required noise value or controller.
• weight: weight value or controller. Default is 1.

local hole = create_connection{ kind="hole", where=tubeAccess, radius=0.01, noise=0.1, weight=0.8 }

viscous-damping

• access or where: required access.
• coeff or coefficient: damping coefficient value or controller. Default is 1.
• weight: weight value or controller. Default is 1.

local damping = create_connection{ kind="viscous-damping", where=access, coeff=0.4, weight=0.9 }

reed

• reedaccess or where1: required reed access.
• tubeaccess or where2: required tube access.
• initialposition: default 0.
• airpressure: value or controller. Default is 20000.
• airdensity: value or controller. Default is 1.2.
• area: reed area value or controller. Default is 1e-8.
• aperturelength: value or controller. Default is 0.000276.
• weight: weight value or controller. Default is 1.

local reed = create_connection{
    kind = "reed",
    reedaccess = reedAccess,
    tubeaccess = tubeAccess,
    initialposition = 0.01,
    airpressure = 2e4,
    airdensity = 1.2,
    area = 1e-8,
    aperturelength = 2.76e-4,
    weight = 0.7
}

normalised-valve

• valveaccess: required valve access.
• tubeaccess or objectaccess: required tube/object access.
• initialposition: default 0.
• breath or gamma: value or controller. Default is 0.
• airdensity: value or controller. Default is 1.2.
• zeta: value or controller. Default is 0.7.
• frontangle: value or controller. Default is 180.
• aperturelength or aperturewidth: value or controller. Default is 0.01.
• weight: weight value or controller. Default is 1.

local valve = create_connection{
    kind = "normalised-valve",
    valveaccess = valveAccess,
    objectaccess = tubeAccess,
    initialposition = 0.001,
    breath = 0,
    airdensity = 1.2,
    zeta = 0.7,
    frontangle = 1e-8,
    aperturelength = 0.01,
    weight = 1
}

mono-fingerboard

• fingeraccess or where1: required finger access.
• stringaccess or where2: required string access.
• initialfingerposition: default 0.02.
• initialstringposition: default 0.01.
• fingerboardposition: default 0.
• weight: weight value or controller. Default is 1.

local fingerboard = create_connection{
    kind = "mono-fingerboard",
    where1 = fingerAccess,
    where2 = stringAccess,
    initialfingerposition = 0.02,
    initialstringposition = 0.01,
    fingerboardposition = 0,
    weight = 1
}

bi-fingerboard

• fingervaccess: required finger vertical access.
• fingerhaccess: required finger horizontal access.
• stringvaccess: required string vertical access.
• stringhaccess: required string horizontal access.
• initialfingerposition: default 0.02.
• initialstringposition: default 0.01.
• fingerboardposition: default 0.
• weight: weight value or controller. Default is 1.

local fingerboard = create_connection{
    kind = "bi-fingerboard",
    fingervaccess = fingerVerticalAccess,
    fingerhaccess = fingerHorizontalAccess,
    stringvaccess = stringVerticalAccess,
    stringhaccess = stringHorizontalAccess,
    initialfingerposition = 0.02,
    initialstringposition = 0.01,
    fingerboardposition = 0,
    weight = 1
}

valve

• objectaccess: required object or tube access.
• valveaccess or valveaccess1: required valve access for one-access valve mode.
• valveaccess1, valveaccess2: required valve accesses for two-access valve mode.
• initialposition: one-access valve default 0.
• initialposition1, initialposition2: two-access valve defaults 0 and 0.
• breath or gamma: value or controller. Default is 0.
• airdensity: value or controller. Default is 1.2.
• underarea: value or controller. Default is 2e-5.
• frontarea: value or controller. Default is 1e-4.
• frontangle: value or controller. Default is 180.
• aperturelength or aperturewidth: value or controller. Default is 0.001.
• weight: weight value or controller. Default is 1.

local valve = create_connection{
    kind = "valve",
    valveaccess = valveAccess,
    objectaccess = tubeAccess,
    initialposition = 0.001,
    breath = 0,
    airdensity = 1.2,
    underarea = 2e-5,
    frontarea = 1e-4,
    frontangle = 180,
    aperturelength = 0.001,
    weight = 1
}

leaky-valve

Uses the same access forms as valve, with extra leakage parameters.

• objectaccess: required object or tube access.
• valveaccess or valveaccess1: required valve access for one-access valve mode.
• valveaccess1, valveaccess2: required valve accesses for two-access valve mode.
• initialposition, initialposition1, initialposition2: defaults are 0.
• breath or gamma: value or controller. Default is 0.
• airdensity: value or controller. Default is 1.2.
• airviscosity: value or controller. Default is 1.78e-5.
• underarea: value or controller. Default is 2e-5.
• frontarea: value or controller. Default is 1e-4.
• frontangle: value or controller. Default is 180.
• aperturelength or aperturewidth: value or controller. Default is 0.001.
• canallength: value or controller. Default is 0.001.
• weight: weight value or controller. Default is 1.

local valve = create_connection{
    kind = "leaky-valve",
    valveaccess = valveAccess,
    objectaccess = tubeAccess,
    initialposition = 0.001,
    breath = 0,
    airdensity = 1.2,
    airviscosity = 1.78e-5,
    underarea = 2e-5,
    frontarea = 1e-4,
    frontangle = 180,
    aperturelength = 0.001,
    canallength = 0.001,
    weight = 1
}

normalised-leaky-valve

• valveaccess: required valve access.
• objectaccess: required object or tube access.
• initialposition: default 0.
• breath or gamma: value or controller. Default is 0.
• airdensity: value or controller. Default is 1.2.
• airviscosity: value or controller. Default is 1.78e-5.
• zeta: value or controller. Default is 0.7.
• frontangle: value or controller. Default is 180.
• aperturelength or aperturewidth: value or controller. Default is 0.001.
• canallength: value or controller. Default is 0.001.
• underarea: value or controller. Default is 2e-5.
• weight: weight value or controller. Default is 1.

local valve = create_connection{
    kind = "normalised-leaky-valve",
    valveaccess = valveAccess,
    objectaccess = tubeAccess,
    initialposition = 0.001,
    breath = 0,
    airdensity = 1.2,
    airviscosity = 1.78e-5,
    zeta = 0.7,
    frontangle = 1e-8,
    aperturewidth = 0.001,
    canallength = 0.01,
    underarea = 1.8e-5,
    weight = 1
}

induction

• stringaccess or where1: required string access.
• magnetaccess or where2: required magnet access.
• signal: required Modalys controller.
• gap: value or controller. Default is 0.001.
• magnetradius: default 0.01.
• length: default 0.02.
• permeability: default 8.737434e-4.
• stringradius: default 0.0004.
• weight: weight value or controller. Default is 1.

local induction = create_connection{
    kind = "induction",
    where1 = stringAccess,
    where2 = magnetAccess,
    signal = signalController,
    gap = 0.001,
    magnetradius = 0.01,
    length = 0.02,
    permeability = 8.737434e-4,
    stringradius = 0.0004,
    weight = 1
}

labium

• tubeaccess, access, objectaccess, or where: required tube access.
• jet: required jet object.
• noise: value or controller. Default is 0.
• vortexfactor: value table or controller. Default is { 4.99, 0.1, 1 }.
• vortextransition: value or controller. Default is 0.005.
• weight: weight value or controller. Default is 1.

local labium = create_connection{
    kind = "labium",
    tubeaccess = tubeAccess,
    jet = jetObject,
    noise = 0,
    vortexfactor = { 4.99, 0.1, 1 },
    vortextransition = 0.005,
    weight = 1
}

Examples

Force

local force = create_connection{
    kind = "force",
    where = access,
    weight = 0.3,
    name = "Force"
}

The where alias is used as the target access. weight can be a number or controller.

Position and Speed

local position = create_connection{
    kind = "position",
    where = access,
    weight = 1
}

local speed = create_connection{
    kind = "speed",
    where = access,
    weight = 1
}

Two-Object Interaction

local strike = create_connection{
    kind = "strike",
    where1 = objectAccess,
    where2 = hammerAccess,
    weight = 0.8
}

local spring = create_connection{
    kind = "spring",
    where1 = access1,
    where2 = access2,
    stiffness = 10000,
    weight = 0.9
}

Reed and Tube

local reed = create_connection{
    kind = "reed",
    reedaccess = reedAccess,
    tubeaccess = tubeAccess,
    airpressure = 20000,
    airdensity = 1.2,
    aperturelength = 2.76e-4,
    weight = 0.7
}

Speed Connection Helper

modalys.create_speed_connection first creates an access from the same parameter table, then creates a speed connection on that access.

local speed = create_speed_connection{
    where = object,
    position = 0.5,
    kind = "trans0",
    weight = 1
}

★     ★
★