Lua: Create Objects with create_object

Description

In Lua context, modalys.create_object creates Modalys objects from a parameter table. The same function is also available as create_object, make_object, and modalys.make_object.

The kind parameter is required. Other parameter names are normalized before use, so common aliases such as freqs, frequencies, amps, amplitudes, objects, and inputs are accepted where relevant.

Lua Syntax

local string = modalys.create_object{
    kind = "mono-string",
    name = "MyString",
    modes = 80,
    length = 1,
    tension = 94.66
}

Supported Kinds

The implementation currently handles these object kinds:

• read-from-file or from-file
• mono-string
• bi-string
• hanging-chain
• harmonic-oscillator
• mono-two-mass
• bi-two-mass
• cello-bridge
• violin-bridge
• circ-membrane
• rect-membrane
• rect-free-bar
• rect-plate
• clamped-circ-plate
• free-circ-plate
• open-open-tube
• closed-closed-tube
• closed-open-tube
• cylindrical-tube
• cylindrical-fractional-delay-tube
• radiator
• finite-element
• jet
• single-point
• multiple-points
• clone
• melt-hybrid
• mix-hybrid
• tri-hybrid

Object-Specific Parameters

read-from-file, from-file

Reads an object from disk.

• path: required object file path.
• name: optional object name.

local object = create_object{ kind="read-from-file", path="my-object.modal" }

mono-string, bi-string

Creates a string object.

• modes: number of modes. Default is 80.
• length: string length. Default is 1.
• tension: string tension. Default is 94.66.
• density: material density. Default is 1000.
• radius: string radius. Default is 0.001.
• young: Young's modulus. Default is 1.0e9.
• freqloss: frequency loss. Default is 1.
• constloss: constant loss. Default is 1.

local monoString = create_object{
    kind = "mono-string",
    name = "MyMonoString",
    modes = 40,
    length = 1,
    tension = 100,
    density = 1000,
    radius = 0.001,
    young = 1e9,
    freqloss = 1,
    constloss = 1
}

local biString = create_object{
    kind = "bi-string",
    name = "MyBiString",
    modes = 40,
    length = 1,
    tension = 100,
    density = 1000,
    radius = 0.001,
    young = 1e9,
    freqloss = 1,
    constloss = 1
}

hanging-chain

Creates a hanging-chain object.

• modes: number of modes. Default is 80.
• length: chain length. Default is 1.
• gravity: gravity value. Default is 9.81.
• freqloss: frequency loss. Default is 1.
• constloss: constant loss. Default is 1.

local chain = create_object{
    kind = "hanging-chain",
    name = "MyChain",
    modes = 40,
    length = 1,
    gravity = 9.81,
    freqloss = 1,
    constloss = 1
}

harmonic-oscillator

Creates a harmonic oscillator.

• mass: oscillator mass. Default is 0.01.
• stiffness: stiffness. Default is 15000.
• freqloss: frequency loss. Default is 100.
• constloss: constant loss. Default is 10.

local oscillator = create_object{
    kind = "harmonic-oscillator",
    name = "MyOscillator",
    mass = 0.01,
    stiffness = 15000,
    freqloss = 100,
    constloss = 10
}

mono-two-mass

Creates a mono-directional two-mass object.

• smallmass: small mass. Default is 0.01.
• largemass: large mass. Default is 0.01.
• stiffness: stiffness. Default is 15000.
• freqloss: frequency loss. Default is 100.
• constloss: constant loss. Default is 0.

local mass = create_object{
    kind = "mono-two-mass",
    name = "MyMonoTwoMass",
    smallmass = 0.01,
    largemass = 0.01,
    stiffness = 15000,
    freqloss = 100,
    constloss = 0
}

bi-two-mass

Creates a bi-directional two-mass object.

• smallmass: small mass. Default is 0.01.
• largemass: large mass. Default is 0.01.
• stiffness1, stiffness2: directional stiffness values. Defaults are 15000 and 15000.
• freqloss1, freqloss2: directional frequency losses. Defaults are 100 and 100.
• constloss1, constloss2: directional constant losses. Defaults are 0 and 0.
• stiffness0, freqloss0, constloss0: compatibility aliases that shift paired values into the 1 and 2 slots.

local mass = create_object{
    kind = "bi-two-mass",
    name = "MyBiTwoMass",
    smallmass = 0.01,
    largemass = 0.01,
    stiffness1 = 15000,
    stiffness2 = 15000,
    freqloss1 = 100,
    freqloss2 = 100,
    constloss1 = 0,
    constloss2 = 0
}

cello-bridge

Creates a cello bridge object.

• centralmass: default 0.0046.
• uppermass: default 0.0059.
• feetmass: default 0.0024.
• ddistance: default 0.032.
• d20distance: default 0.01625.
• hdistance: default 0.052.
• adistance: default 0.035.
• i20distance: default 0.026.
• d2stiffness: default 716.8.
• s1stiffness: default 360000.
• freqloss: default 10.
• constloss: default 10.

local bridge = create_object{
    kind = "cello-bridge",
    name = "MyCelloBridge",
    centralmass = 0.0046,
    uppermass = 0.0059,
    feetmass = 0.0024,
    ddistance = 0.032,
    d20distance = 0.01625,
    hdistance = 0.052,
    adistance = 0.035,
    i20distance = 0.026,
    d2stiffness = 716.8,
    s1stiffness = 360000,
    freqloss = 10,
    constloss = 10
}

violin-bridge

Creates a violin bridge object.

• centralmass: default 0.00177.
• feetmass: default 0.00038.
• edistance: default 0.013.
• adistance: default 0.01625.
• hdistance: default 0.021.
• bdistance: default 0.0065.
• stiffness: default 1300000.
• freqloss: default 10.
• constloss: default 10.

local bridge = create_object{
    kind = "violin-bridge",
    name = "MyViolinBridge",
    centralmass = 0.00177,
    feetmass = 0.00038,
    edistance = 0.013,
    adistance = 0.01625,
    hdistance = 0.021,
    bdistance = 0.0065,
    stiffness = 1300000,
    freqloss = 10,
    constloss = 10
}

circ-membrane

Creates a circular membrane.

• modes: default 80.
• radius: default 0.5.
• tension: default 1000.
• density: default 0.25.
• freqloss: default 1.
• constloss: default 1.

local membrane = create_object{
    kind = "circ-membrane",
    name = "MyCircularMembrane",
    modes = 40,
    radius = 0.5,
    tension = 1000,
    density = 0.25,
    freqloss = 1,
    constloss = 1
}

rect-membrane

Creates a rectangular membrane.

• modes: default 80.
• length1, length2: default 0.5 and 0.5.
• length0: compatibility alias that shifts paired length values into length1 and length2.
• tension: default 1000.
• density: default 0.1.
• freqloss: default 1.
• constloss: default 1.

local membrane = create_object{
    kind = "rect-membrane",
    name = "MyRectMembrane",
    modes = 40,
    length1 = 0.5,
    length2 = 0.5,
    tension = 1000,
    density = 0.1,
    freqloss = 1,
    constloss = 1
}

rect-free-bar

Creates a rectangular free bar.

• modes: default 80.
• length: default 1.
• width: default 0.05.
• thickness: default 0.01.
• density: default 1000.
• young0, young1: default 1.2e10 and 1.2e10.
• young2: compatibility alias that shifts paired Young's modulus values into young0 and young1.
• poisson: default 0.25.
• freqloss: default 1.
• constloss: default 1.

local bar = create_object{
    kind = "rect-free-bar",
    name = "MyBar",
    modes = 40,
    length = 1,
    width = 0.05,
    thickness = 0.01,
    density = 1000,
    young0 = 1.2e10,
    young1 = 1.2e10,
    poisson = 0.25,
    freqloss = 1,
    constloss = 1
}

rect-plate

Creates a rectangular plate.

• modes: default 80.
• length0, length1: default 0.5 and 0.5.
• length2: compatibility alias that shifts paired length values into length0 and length1.
• thickness: default 0.01.
• density: default 7800.
• young: default 1.0e9.
• poisson: default 0.3.
• freqloss: default 10.
• constloss: default 10.

local plate = create_object{
    kind = "rect-plate",
    name = "MyRectPlate",
    modes = 40,
    length0 = 0.5,
    length1 = 0.5,
    thickness = 0.01,
    density = 7800,
    young = 1e9,
    poisson = 0.3,
    freqloss = 10,
    constloss = 10
}

clamped-circ-plate, free-circ-plate

Creates a circular plate.

• modes: default 80.
• radius: default 0.5.
• thickness: default 0.01.
• density: default 7800.
• young: default 2e11.
• poisson: default 0.3.
• freqloss: default 1.
• constloss: default 1.

local clamped = create_object{
    kind = "clamped-circ-plate",
    name = "MyClampedPlate",
    modes = 40,
    radius = 0.5,
    thickness = 0.01,
    density = 7800,
    young = 2e11,
    poisson = 0.3,
    freqloss = 1,
    constloss = 1
}

local free = create_object{
    kind = "free-circ-plate",
    name = "MyFreePlate",
    modes = 40,
    radius = 0.5,
    thickness = 0.01,
    density = 7800,
    young = 2e11,
    poisson = 0.3,
    freqloss = 1,
    constloss = 1
}

open-open-tube, closed-closed-tube, closed-open-tube

Creates a modal tube.

• modes: default 80.
• length: default 1.
• airelasticity: default 0.00000721.
• airdensity: default 1.2.
• radius1, radius2: default 0.01 and 0.01.
• radius0: compatibility alias that shifts paired radius values into radius1 and radius2.
• freqloss: default 1.
• constloss: default 1.

local closedClosed = create_object{
    kind = "closed-closed-tube",
    name = "MyClosedClosedTube",
    modes = 20,
    length = 1,
    airelasticity = 0.00000721,
    airdensity = 1.2,
    radius1 = 0.01,
    radius2 = 0.01,
    freqloss = 1,
    constloss = 1
}

local closedOpen = create_object{ kind="closed-open-tube", name="MyClosedOpenTube", length=1 }
local openOpen = create_object{ kind="open-open-tube", name="MyOpenOpenTube", length=1 }

cylindrical-tube, cylindrical-fractional-delay-tube

Creates a cylindrical tube.

• length: default 1.
• radius: default 0.01.
• rho: air density. Default is 1.2.
• aircelerity: default 340.
• constloss: default 1.

local tube = create_object{
    kind = "cylindrical-tube",
    name = "MyCylindricalTube",
    length = 1,
    radius = 0.01,
    rho = 1.2,
    aircelerity = 340,
    constloss = 1
}

local fractional = create_object{
    kind = "cylindrical-fractional-delay-tube",
    name = "MyFractionalTube",
    length = 1,
    radius = 0.01
}

radiator

Creates a radiator object.

• radius: default 0.01.
• angle: default 0.
• rho: air density. Default is 1.2.
• density: alias for rho.
• celerity: default 340.

local radiator = create_object{
    kind = "radiator",
    name = "MyRadiator",
    radius = 0.01,
    angle = 0,
    rho = 1.2,
    celerity = 340
}

finite-element

Creates a finite-element object.

• mesh: required finite-element mesh.
• block: optional constrained submesh.
• modes: default 80.
• density: default 7800.
• thickness: default 0.001.
• young: default 1.95e11.
• poisson: default 0.2.
• freqloss: default 1.
• constloss: default 1.
• async: passed to modalys.compute_modes.

local mesh = create_mesh{ kind="read-from-file", path="diapason.mesh" }

local object = create_object{
    kind = "finite-element",
    name = "MyFiniteElement",
    mesh = mesh,
    modes = 30,
    density = 7700,
    thickness = 0.001,
    young = 1.95e11,
    poisson = 0.2,
    freqloss = 0.3,
    constloss = 0.1
}

jet

Creates a jet object.

• pressure: default 1.
• airdensity: default 1.2.
• airspeed: default 340.
• length: default 0.03.
• width: default 0.02.
• height: default 0.001.
• fluelabiumdistance: default 0.004.
• labiumposition: default 0.0002.
• mouthsurface: default 0.00008.

local jet = create_object{
    kind = "jet",
    name = "MyJet",
    pressure = 1,
    airdensity = 1.2,
    airspeed = 340,
    length = 0.03,
    width = 0.02,
    height = 0.001,
    fluelabiumdistance = 0.004,
    labiumposition = 0.0002,
    mouthsurface = 0.00008
}

single-point

Creates a single-point modal object.

• freq, frequency, freqs, or frequencies: mode frequencies. Default is { 440 }.
• bw, bws, bandwidth, or bandwidths: mode bandwidths. Default is { 1 }.
• amp, amps, amplitude, or amplitudes: mode amplitudes. Default is { 1 }.

Each of these can be a table of values or a controller.

local point = create_object{
    kind = "single-point",
    name = "MySinglePoint",
    freqs = { 220, 440, 660 },
    bws = { 8, 4, 2 },
    amps = { 1, 0.5, 0.25 }
}

multiple-points

Creates a multiple-points modal object.

• freq, frequency, freqs, or frequencies: required mode frequencies.
• bw, bws, bandwidth, or bandwidths: required mode bandwidths.
• amp, amps, amplitude, amplitudes, or shapes: required modal shapes.

shapes must be a table of mode shapes. Each mode shape is either a table of point amplitudes or a dynamic controller.

local object = create_object{
    kind = "multiple-points",
    name = "MyMultiplePoints",
    freqs = { 220, 440, 660 },
    bws = { 8, 4, 2 },
    shapes = {
        { 1, 0.1 },
        { 0.8, 0.08 },
        { 0.6, 0.06 }
    }
}

clone

Creates a clone of an existing object.

• original: required source object.

local clone = create_object{
    kind = "clone",
    name = "MyClone",
    original = sourceObject
}

melt-hybrid

Creates a melt-hybrid object.

• input, inputs, or objects: required table of source objects.
• interpolation: interpolation value or controller. Default is a zero table matching the input dimension.

local hybrid = create_object{
    kind = "melt-hybrid",
    name = "MyMeltHybrid",
    objects = { object1, object2, object3 },
    interpolation = { 0.3, 0.5, 0.2 }
}

mix-hybrid

Creates a mix-hybrid object.

• object1: required first object.
• object2: required second object.
• interpolation: interpolation value or controller. Default is 0.

local hybrid = create_object{
    kind = "mix-hybrid",
    name = "MyMixHybrid",
    object1 = object1,
    object2 = object2,
    interpolation = 0.5
}

tri-hybrid

Creates a tri-hybrid object.

• object1: required first object.
• object2: required second object.
• object3: required third object.
• interpolation: interpolation value or controller. Default is { 1, 0, 0 }.

local hybrid = create_object{
    kind = "tri-hybrid",
    name = "MyTriHybrid",
    object1 = object1,
    object2 = object2,
    object3 = object3,
    interpolation = { 0.9, 0.1, 0.3 }
}

Common Post-Creation Parameters

After creating the object, mlys.lua may apply these optional parameters:

• pitch: pitchbend value or controller.
• pitchparameter: physical parameter to pitchbend. If omitted, mlys.lua chooses a known parameter for supported object kinds.
• async: passed to modalys.compute_modes.

Examples

Basic Modal Object

local object = create_object{
    kind = "single-point",
    name = "Object1",
    freqs = { 220, 440, 660 },
    bws = { 8, 4, 2 },
    amps = { 1, 0.5, 0.25 }
}

Object with Dynamic Parameters

Numerical parameters can be passed directly, or as Modalys controllers.

local bandwidths = create_controller{
    kind = "dynamic",
    value = { 8, 4, 2 },
    name = "Bandwidths"
}

local object = create_object{
    kind = "single-point",
    name = "Object2",
    freqs = { 220, 440, 660 },
    bws = bandwidths,
    amps = { 1, 0.5, 0.25 }
}

Finite Element Object

local mesh = create_mesh{
    kind = "read-from-file",
    path = "diapason.mesh"
}

local object = create_object{
    kind = "finite-element",
    name = "Diapason",
    mesh = mesh,
    modes = 30,
    density = 7700,
    young = 1.95e11,
    poisson = 0.2
}

For finite-element objects, mesh is required. block is optional and defines the constrained part of the mesh.

Clone and Hybrids

local clone = create_object{
    kind = "clone",
    name = "Clone1",
    original = object
}

local hybrid = create_object{
    kind = "mix-hybrid",
    name = "Hybrid1",
    object1 = objectA,
    object2 = objectB,
    interpolation = 0.5
}

Notes

After an object is created, modalys.create_object calls modalys.compute_modes. If pitch is supplied and the object kind has a known pitch parameter, a pitch controller is attached internally.

★     ★
★