Interfaces in WWD: ports, anchoring and how a tissue binds to a mechanism

Definition

An interface is a declared boundary or connection through which mechanical load, electrical signals, or fluid may pass. Every interface MUST have an identifier, type, modality, geometry or region, frame, and direction convention, MUST identify a target region or delegated geometry feature, MUST define mating geometry or a referenced interface standard, MUST identify material or surface state relevant to connection, and MUST identify allowable operating conditions. Compatibility requirements MUST be testable and MUST NOT rely solely on labels. Every declared interface of a component IS a port of that component, a connection MUST name exactly two ports and both MUST resolve, and two ports MUST NOT be connected unless their kinds are compatible.

An interface belongs to a component. It names a region of that component, a frame, a direction convention and the conditions under which the connection holds. A muscle strip declares two attachment loops. A neuron tile declares a recording array, a stimulation site and an optical access window. A rig declares the posts the strip is mounted on.

Section 14.7 gives the same objects a second reading. Every declared interface of a component is a port, and a package that describes an assembly rather than one article carries a list of connections between ports. Resolution, kind compatibility and grounding are checkable from the file, with no solver and no geometry.

Interface facts

Section	14, with ports and connections in 14.7
Modalities	7, closed
Interface kinds	connector, boundary, test_interface, realized_connection
Roles	closed per modality for 4 of 7
Port kinds	6, including ground
Compatible pairs	7, ground to mechanical among them
Connection kinds	7
Diagnostics	N01 to N14
Netlist location	design.connections, in Core

What a declaration carries

Section 14.1 and section 7.5.

Interface declaration
Slot	Status	Rule
id	required	Unique within the package. Every interface MUST have an identifier.
modality	required	The physical nature of the connection. The vocabulary is closed and a consumer MUST refuse an unlisted value.
role	required for mechanical and electrical	The mechanical role, or the recording, stimulation, reference, ground or combined role. Section 14.3 requires the electrical roles to be distinguished.
region or target	required	A target region or delegated geometry feature. It MUST exist.
frame and direction	required	The local frame and the outward or positive direction.
mating geometry or standard	required	Mating geometry, or a referenced interface standard alongside at least one measurable parameter.
material or surface state	required	The material or surface state relevant to connection.
operating conditions	required	Allowable operating conditions. Absence is reported as a warning.
kind	closed vocabulary	connector, boundary, test_interface or realized_connection. What the interface is, as distinct from what passes through it.
port_kind	optional, required for ground	mechanical, electrical, fluidic, optical, thermal or ground. Where declared, the declared kind governs.

The four interface kinds
kind	What it is	Obligation
connector	A design-side mating feature.	MUST state mating geometry or a referenced standard.
boundary	An exposed surface across which something passes.	MUST state a direction convention.
test_interface	Exists only during measurement.	MUST identify the fixture it engages, and a named fixture MUST resolve to a component of kind device.
realized_connection	A connection that was actually made.	Belongs to a realization, never to a design.

Every required interface parameter MUST use scalar-or-field semantics where spatial variation is meaningful. A dimension used to mate an interface MUST reference that interface, and a dimension referenced by an interface MUST declare a tolerance or a permitted interval.

Modalities and roles

The role vocabulary of the Core registry, per modality.

The modality vocabulary is closed and a consumer MUST refuse an unlisted value. The interface_role registry entry is closed per modality where a worked case exists, and open for chemical, informational and thermal. A consumer encountering an unrecognised role on those three MUST report it as a warning and MUST NOT refuse the package.

registry/core-vocabularies.json, interface_role by_modality
modality	port kind	Roles	Vocabulary	Modality obligation
mechanical	mechanical	anchor, attachment_loop, bearing_surface, bonded_face, clamp_zone, load_boundary, tendon_end	closed	Role, load directions and sign conventions, applicable dimensions and tolerances.
electrical	electrical	combined, ground, recording, reference, stimulation	closed	Electrode or conductor geometry, material, channel identity, reference frame, contact type.
fluidic	fluidic	inlet, outlet, perfusion_channel, port, reservoir, sterile_barrier	closed	Port geometry, flow direction convention, connected compartment or region, working fluid identity.
optical	optical	combined, illumination, imaging_access, optical_readout, photostimulation	closed	Optical role, optical path region or surface, intervening materials and their optical state.
thermal	thermal	not closed in 0.1	open, unknown role is a warning	The common obligations of section 14.1.
chemical	not mapped	not closed in 0.1	open, unknown role is a warning	The common obligations of section 14.1.
informational	not mapped	not closed in 0.1	open, unknown role is a warning	The common obligations of section 14.1.

A multimodal interface MUST satisfy every applicable modality rule. An interface MUST declare whether it is a design-side connector, exposed boundary, virtual test interface, or realized connection.

Mechanical attachment and anchoring

Section 14.2, and the anchor role.

Mechanical interface obligations
Slot	Rule	Code
Role	A mechanical interface MUST declare its mechanical role, such as attachment loop, clamp zone, bonded face, tendon-like end, bearing surface, or load application boundary.	N04_NO_ROLE
Direction	It MUST identify load directions and sign conventions. A load limit stated with no direction or sign convention is refused.	N05_NO_DIRECTION
Dimensions	It MUST declare applicable dimensions and tolerances. A dimension used to mate an interface MUST reference that interface and MUST declare a tolerance or a permitted interval.	Z06_MATING_DIMENSION_NO_TOLERANCE
Loops	A flexible loop interface MUST declare clear opening dimensions, cross-section or geometry reference, attachment region, and allowable loading directions.	N06_LOOP_UNDERSPECIFIED
Limits	It SHOULD declare allowable preload, displacement, rotation, force, moment, stress, strain, and cycle limits as applicable.	N08_NO_OPERATING_LIMITS
Fixtures	A mechanical interface used in a test MUST identify the fixture or fixture protocol. A fixture is a component, not a note on a method, and MUST NOT be represented only by a vendor name or catalog number.	section 14.6
Conditions	Contact, bonded, pinned, clamped and prescribed-motion conditions MUST be distinguished. An assembly distinguishes them on the connection.	section 14.2

an attachment loopmuscle-strip-designed.wwd

{
  "id": "iface/loop-a",
  "modality": "mechanical",
  "role": "attachment_loop",
  "region": "region/loop-a",
  "clear_opening": "0.6 mm",
  "allowable_axial_force": "5 mN",
  "load_direction": "+x",
  "sign_convention": "positive is tension along the loop axis"
}

The strip declares iface/loop-a and iface/loop-b, one at each end, on region/loop-a and region/loop-b. Each states a clear opening, an allowable axial force, a load direction and a sign convention. An allowable force with no direction does not say whether it is tension or compression.

a ground portpinwheel-study.wwd

{
  "id": "iface/post-a",
  "modality": "mechanical",
  "port_kind": "ground",
  "role": "anchor",
  "region": "region/post-a",
  "dimensions": ["post_diameter"],
  "allowable_axial_force": "20 mN",
  "load_direction": "-x",
  "sign_convention": "positive is tension along the strip axis",
  "note": "held by the stage: 14.7 makes ground a port kind, and no modality maps to it, so a fixed post says so here"
}

The rig post is mechanical in modality and ground in port kind. Ground is a kind and not a modality, so no modality maps to it and the post declares it directly. Its role is anchor.

Electrical interfaces

Section 14.3, recording and stimulation sites.

Electrical interface obligations
Slot	Rule
Geometry and identity	An electrical interface MUST identify electrode or conductor geometry, material, channel identity, and reference frame.
Roles	It MUST distinguish recording, stimulation, reference, ground, and combined roles.
Contact type	It MUST identify contact type, such as planar electrode, penetrating electrode, conductive hydrogel, wire, pad, or connector.
Site detail	It SHOULD declare electrode area, center coordinate, pitch, impedance characterization conditions, safe stimulus limits, and channel map where applicable.
Impedance	Impedance MUST identify frequency and measurement conditions.
Stimulus limits	Voltage and current limits MUST identify reference and waveform conditions.
Arrays	An MEA interface SHOULD reference a delegated geometry or a table of electrode coordinates. Electrophysiology recordings SHOULD be delegated to NWB.
Channel map	A channel map MUST preserve stable channel identities across design, simulation, and measurement.

a recording siteneurontile-asbuilt.wwd

{
  "id": "iface/mea",
  "modality": "electrical",
  "role": "recording",
  "region": "region/electrode-array",
  "electrode_count": 60,
  "pitch": "200 um",
  "electrode_diameter": "30 um",
  "material": "titanium_nitride",
  "impedance_conditions": { "frequency_hz": 1000, "medium": "PBS" },
  "max_impedance": "1000 kohm",
  "operating_temperature": "37 degC",
  "channel_map": "delegated:nwb"
}

Sixty electrodes on region/electrode-array, with pitch, diameter, material and a maximum impedance stated with the frequency and medium it was characterised in. The channel map is delegated to NWB and preserves stable channel identities across design, simulation and measurement.

a stimulation siteneurontile-asbuilt.wwd

{
  "id": "iface/stim",
  "modality": "electrical",
  "role": "stimulation",
  "region": "region/electrode-array",
  "safe_charge_density": "30 uC/cm2",
  "charge_balancing": "biphasic, symmetric, zero net charge",
  "max_current": "100 uA",
  "waveform": "biphasic"
}

The same region, a second interface, role stimulation. Safe charge density, charge balancing, a maximum current and a waveform. Voltage and current limits MUST identify reference and waveform conditions.

The tile also declares iface/optical, role imaging_access, with a wavelength range, a working distance and its intervening materials. An optical interface MUST identify the intervening materials and their relevant optical state, and MUST NOT be inferred from substrate material alone.

Ports, nets and grounding

Section 14.7.

A port is addressed component#interface. A connection names two of them, and both MUST resolve. Two ports MUST NOT be connected unless their kinds are compatible: a port is compatible with its own kind, and ground is compatible with mechanical and with itself. No other cross-kind pair is compatible in Core, and an extension defining a transducer MUST declare the compatibility it introduces and MUST be declared in extensionsRequired.

A ground port is a point held by the assembly frame rather than by another part. Two grounds joined to each other transmit nothing, and an assembly with no ground has no frame to move in. A port named by no connection MUST be reported: an unconnected port is not always an error, and it is always a fact a reader needs.

Modality to port kind, and what each kind joins to
Interface modality	Port kind	Compatible with
mechanical	mechanical	mechanical, ground
electrical	electrical	electrical
fluidic	fluidic	fluidic
perfusion	fluidic	fluidic
optical	optical	optical
thermal	thermal	thermal
no modality maps to it	ground, declared explicitly	ground, mechanical

the netlistpinwheel-study.wwd

"connections": [
  { "id": "net/anchor",
    "from": "component/muscle-strip#iface/loop-a",
    "to": "component/rig#iface/post-a",
    "kind": "rigid_attachment",
    "note": "the fixed end" },
  { "id": "net/drive",
    "from": "component/muscle-strip#iface/loop-b",
    "to": "component/lever#port/in",
    "kind": "pin_joint",
    "note": "the strip pulls the lever's short arm" },
  { "id": "net/fulcrum",
    "from": "component/lever#port/pivot",
    "to": "component/rig#iface/post-b",
    "kind": "ground" },
  { "id": "net/output",
    "from": "component/lever#port/out",
    "to": "component/pinwheel#port/rim",
    "kind": "contact",
    "note": "the amplified stroke drives the rim tangentially" },
  { "id": "net/axle",
    "from": "component/pinwheel#port/axle",
    "to": "component/rig#iface/post-a",
    "kind": "ground" }
]

Five connections. net/anchor ties the strip's fixed loop to a ground post. net/drive pins the strip's other loop to the lever tip. net/fulcrum and net/axle reach ground ports, so the assembly is held. net/output is contact, not bonded, and the two carry load differently.

Connection kinds: bonded, clamped, contact, ground, pin_joint, prescribed_motion, rigid_attachment. A connection that declares no kind is a stated adjacency and not a stated constraint.

The mech: prefix

How a mechanism assembly is carried in a package.

The netlist is Core and the wwd.mechanism extension does not carry one. Connections live in design.connections, and every conformant validator checks them. The extension owns the parts, their poses and their dynamic parameters. A part that offers ports MUST reference a Core component, so every end of every connection resolves in Core.

A prefix on its own identifies nothing. A manifest MUST bind every prefix it uses in extensionPrefixes, an object mapping each prefix to the versioned extension URI it abbreviates, and every URI named there MUST also appear in extensionsUsed. A namespaced key whose prefix is unbound MUST be reported as undeclared extension content. A consumer that re-emits a package MUST preserve every namespaced key it did not interpret, on the object where it appeared, with its value unchanged, and MUST preserve its prefix binding with it.

prefix bindingwwd/manifest.json

"extensionPrefixes": { "mech": "https://wetwareworld.com/ext/wwd.mechanism/0.1" },
"extensionsUsed":    [ "https://wetwareworld.com/ext/wwd.mechanism/0.1" ]

The prefix mech bound to a versioned URI, and the same URI in the used list. An extension identifier whose last segment is not a version is refused as P08_EXTENSION_URI_UNVERSIONED.

the stagewwd.mechanism 0.1

"mech:stage": {
  "frame": {"axes": ["x","y","z"], "axis_units": "mm",
            "origin": "stage floor at the assembly origin"},
  "parts": [
    {"id": "p1", "type": "component", "component": "component/strip",
     "pose": {"translation": ["0 mm", "0 mm", "0 mm"]}},
    {"id": "p2", "type": "lever", "component": "component/lever",
     "params": {"arm_in": "3 mm", "arm_out": "9 mm"},
     "pose": {"translation": ["6 mm", "0 mm", "0 mm"], "rotation_deg": [0,0,0]}}
  ]
}

A stage part is a pose of something, not the thing itself, so one strip component can appear twice in one assembly without being copied. The catalogue part SHOULD be published as a library part and instantiated.

Where each half of a mechanism sits
Content	Carried by	Rule
Netlist	Core	design.connections, checked by every conformant validator.
Ports	Core	The declared interfaces of the components a stage part names.
Parts and poses	mech:stage	A part is a pose of something. A part that offers ports MUST reference a Core component.
Dynamic parameters	mech:parts[].params	Mass, arm lengths, stiffness, inertia, drag coefficient, slip torque.
Attachment compliance	mech:connection_params	Keyed by Core connection id. Compliance and backlash on a load-bearing connection.
Boundary conditions	mech:boundary_conditions	Each entry names what is held, driven or free. The target names a stage part, a port address or a Core connection id, and MUST resolve to one of them.
Tissue coupling	mech:tissue_models	The models that supply the force the tissue develops.
Outputs	mech: quantities	mech:angular_velocity, mech:revolutions, mech:output_work_per_cycle, mech:transmission_efficiency, mech:stroke, mech:limit_reached.

A type the extension does not define MUST be namespaced by whoever does define it. The ground ports in its part catalogue are why section 14.7 requires port_kind to be declared for ground rather than derived from a modality. A study that reaches stroke_limit, holding_torque or slip_torque MUST report mech:limit_reached naming the element.

What the validator refuses

Code, trigger, and the change the writer makes.

The reference implementation is validator/wwd/interfaces.py for section 14 and validator/wwd/ports.py for section 14.7. A package carrying no connections is not an assembly, and the port checks return nothing for it. Once a package carries one connection, every declared port of every component is in scope.

Interface and port diagnostics
Code	Severity	Trigger	Change
N01_BAD_MODALITY	ERROR	The interface modality is outside the Core set.	Declare one of chemical, electrical, fluidic, informational, mechanical, optical, thermal.
N02_NO_TARGET	ERROR	The interface names no region or geometry feature, or names one that is not a region of the component.	Name a region or delegated geometry feature that exists. An interface attached to nothing cannot be loaded, imaged or connected.
N03_LABEL_ONLY	ERROR	Compatibility is asserted only by standard, connector, part_number or vendor, with no measurable parameter.	State at least one measurable parameter alongside the reference.
N04_NO_ROLE	ERROR	A mechanical interface declares no role, or a role outside the Core set.	Declare one of anchor, attachment_loop, bearing_surface, bonded_face, clamp_zone, load_boundary, tendon_end.
N05_NO_DIRECTION	ERROR	A force, load or stress limit is stated with no load_direction, sign_convention or outward_direction.	Declare the direction and the sign convention beside the limit.
N06_LOOP_UNDERSPECIFIED	ERROR	An attachment_loop declares no clear_opening.	Declare the clear opening dimension the fixture is selected against.
N08_NO_OPERATING_LIMITS	WARNING	A mechanical, electrical, fluidic or thermal interface carries no key beginning allowable, max, min, safe or operating, and no duty_limit, impedance or temperature_range.	State the allowable operating conditions.
N10_CONNECTION_DANGLING	ERROR	A connection is not an object, names other than two ports, or names an end that resolves to no port in the package.	Name exactly two port addresses that both resolve.
N11_PORT_KIND_UNKNOWN	ERROR	A connected port has no port kind, because its modality is not one section 14.7 maps.	Declare a modality the mapping covers, or declare port_kind. An unrecognised modality is reported, never defaulted.
N12_PORT_KIND_MISMATCH	ERROR	A connection joins two ports whose kinds are not compatible.	Join kinds Core permits, or declare the transducer extension that introduces the cross-kind pair in extensionsRequired.
N13_PORT_UNCONNECTED	WARNING	A declared port is named by no connection in a package that carries connections.	Connect it, or read the warning as the fact it is. A spare electrode and an unused loop are both legitimate.
N14_ASSEMBLY_UNGROUNDED	ERROR	No connection in the assembly reaches a ground port.	Ground one port. An assembly with no ground has no frame to move in.
I06_WRONG_REFERENT	ERROR	A lot acceptance criterion targets an interface.	Point the criterion at an object of the required kind.

Test-suite vectors covering interfaces and ports
Vector	Section	Reports	What it holds
invalid-load-limit-without-direction	14	N05_NO_DIRECTION	A mechanical interface stating an allowable force with no direction or sign convention.
invalid-compatibility-by-label-only	14	N03_LABEL_ONLY	Compatibility asserted only by a standard name.
invalid-interface-targets-nothing	14	N02_NO_TARGET	An interface attached to a region that does not exist.
valid-assembly-netlist	14.7	none	A tissue loop pinned to a lever tip and the lever fulcrum grounded. Every port resolves, the kinds are compatible, and something is held.
invalid-connection-dangling	14.7	N10_CONNECTION_DANGLING	A connection to a port that does not exist.
invalid-port-kind-unknown	14.7	N11_PORT_KIND_UNKNOWN	A connected port whose modality section 14.7 does not map to a port kind.
invalid-port-kind-mismatch	14.7	N12_PORT_KIND_MISMATCH	An optical port connected to a mechanical one.
invalid-assembly-ungrounded	14.7	N14_ASSEMBLY_UNGROUNDED	An assembly nothing holds.
invalid-criterion-targets-an-interface	4	I06_WRONG_REFERENT	An interface is not something a lot acceptance criterion can be about.

N08_NO_OPERATING_LIMITS and N13_PORT_UNCONNECTED are warnings. Every other code in the table is an error.

What an interface does not specify

The boundary of section 14.

Outside the interface object
Not carried	Rule
Dynamics	Mass, inertia, damping, backlash and the direction a clutch rectifies in. Core describes the parts, the interfaces and the connections, and has no opinion about dynamics.
Poses and parts	Where a part sits in an assembly. A stage part is a pose of something, not the thing itself, and it belongs to the mechanism extension.
Geometry libraries	What a lever looks like. A part is a mass, an inertia and a set of parameters, and shape belongs to a delegated geometry asset under the Core integrity rules.
Constraint by diagram	A connection that declares no kind is a stated adjacency and not a stated constraint, and a consumer MUST NOT infer one.
Compatibility by label	A standard name or part number. Compatibility requirements MUST be testable and MUST NOT rely solely on labels.
Optical access by material	An optical interface MUST NOT be inferred from substrate material alone.
Acceptance	An interface is not the referent of a lot acceptance criterion.

New interface modalities MAY be extensions when mechanical, electrical and fluidic semantics are insufficient. A producer MUST mark an extension required whenever ignoring it could change interface compatibility.

Questions

What must every interface declare?

Every interface MUST have an identifier, type, modality, geometry or region, frame, and direction convention. Section 14.1 adds that every interface MUST identify a target region or delegated geometry feature, MUST define its local frame and outward or positive direction, MUST define mating geometry or a referenced interface standard, MUST identify material or surface state relevant to connection, and MUST identify allowable operating conditions. Every required interface parameter MUST use scalar-or-field semantics where spatial variation is meaningful. An interface MAY declare compatibility requirements for another interface, and those requirements MUST be testable and MUST NOT rely solely on labels.

Which interface vocabularies are closed?

The modality vocabulary is closed to chemical, electrical, fluidic, informational, mechanical, optical and thermal, and a consumer MUST refuse an unlisted modality. The kind vocabulary is closed to connector, boundary, test_interface and realized_connection. The role vocabulary is closed per modality where a worked case exists: mechanical, electrical, fluidic and optical. Roles for chemical, informational and thermal are not closed in 0.1, and a consumer encountering an unrecognised role on those three MUST report it as a warning and MUST NOT refuse the package.

What is a port?

Every declared interface of a component IS a port of that component. A non-living part MAY declare ports that are not interfaces of a living article, and those ports MUST carry the same obligations section 14.1 places on an interface. A port MUST have a kind, which for an interface is determined by its modality: mechanical to mechanical, electrical to electrical, fluidic and perfusion to fluidic, optical to optical, thermal to thermal. A port kind MUST NOT be inferred from any other property, and a modality the table does not list MUST be reported rather than mapped to mechanical. An interface MAY declare port_kind explicitly, and where it does, the declared kind governs.

What does a connection assert?

An assembly is a set of parts and a set of connections between named points on them. A connection MUST name exactly two ports and both MUST resolve. Two ports MUST NOT be connected unless their kinds are compatible: a port is compatible with its own kind, ground is compatible with mechanical and with itself, and no other cross-kind pair is compatible in Core. A connection MAY declare which of bonded, clamped, contact, ground, pin_joint, prescribed_motion or rigid_attachment it is. A connection that declares no kind is a stated adjacency and not a stated constraint, and a consumer MUST NOT infer one.

What is a ground port?

A ground port is a point held by the assembly frame rather than by another part. Ground is a sixth port kind and is not a modality. Because no modality maps to it, a ground port MUST declare port_kind. Ground is compatible with mechanical and with itself. An assembly whose connections reach no ground port is reported as N14_ASSEMBLY_UNGROUNDED.

Where does the netlist live when a package describes a mechanism?

In Core. Connections live in design.connections and every conformant validator checks them. The wwd.mechanism extension, prefix mech, carries the parts, their poses and their dynamic parameters. A part that offers ports MUST reference a Core component, so every end of every connection resolves in Core. The prefix MUST be bound in extensionPrefixes to the versioned extension URI it abbreviates, every URI named there MUST also appear in extensionsUsed, and a key whose prefix is unbound MUST be reported as undeclared extension content.

When are these rules checkable?

Before simulation. Compatibility, resolution and grounding are checkable from the file, with no solver and no geometry. A package that states an assembly SHOULD be checked against these rules before any study is run against it. The test suite carries valid-assembly-netlist as the whole section 14.7 rule set passing, and invalid-connection-dangling, invalid-port-kind-unknown, invalid-port-kind-mismatch and invalid-assembly-ungrounded as the four ways it fails.

What is a fixture, and what does it have to do with an interface?

A mechanical interface used in a test MUST identify the fixture or fixture protocol. A fixture is a component, not a note on a method. A criterion whose registered assay declares that it requires a fixture MUST name one, and a named fixture MUST resolve to a component of kind device. A fixture component SHOULD declare the property that converts its raw observable into the reported quantity, with the fixture as the property target and the derivation stated as a derived quantity. A fixture MUST NOT be represented only by a vendor name or catalog number.

Continue

Related pages.

The WWD file format. Container, manifest, design and results documents.
Property fields. Scalar-or-field slots and the five Core backings.
Causal roles. control, response, context and derived.
Acceptance criteria. Named assays, fixtures, recomputed verdicts and yield.
As-built. Designed, simulated and measured in one package.
Design rules. The design-for-manufacture checks, including charge balancing.
Conformance. The test vectors and the conformance classes.
The reference validator. Every diagnostic code and how to run it.
The WWD 0.1 draft specification. All normative sections with anchors.