The Library of Alexandria Mechasphere Modeling Alexandria Home | Up One Level | Home | Download | Usage | Modeling | Programming

This section is intended for users who already understand basic usage and wish to understand how to read, create, and modify models. For more about understanding or extending the source code, visit the Programming section.

Table of Contents

• About this Document
• Key Concepts
• Element Types
• Commonly Used Attributes

About this Document

First, let me apologize for the complexity of this concept. As I write this, the approach I'm taking to a design specification for models of the world is completely novel to me. If my guess is right, it is novel to most every other programmer as well. I write this file to help myself and others understand how properly to construct or interpret a model specification. If this looks anything like a technical reference, I can assure you that's purely a coincidence.

Key Concepts

Segmentation

The Mechasphere model definition files attempt to take advantage of repetition through what biologists call "segmentation". Many insects illustrate this principal very well. Take a millipede, for example, with its long string of nearly identical segments with nearly identical legs. Rather than cut and paste and then modify copies of a chunk of, say, particles, a model can define a segment composed of particles. To simulate a millipede, for instance, we might define a leg segment once and then instantiate that model in some other location and perhaps at a different angle.

I've referred for simplicity of segments of particles, but the same concept applies to brain components, referred to here as "circuits". An example of how this is useful would be an arrangement of brain components useful for driving one leg of our millipede being duplicated once for each leg. This would automatically happen if a brain chassis particle hosting such a circuit were part of a leg segment that gets copied. But this way, such circuits can also be duplicated within the same brain chassis particle, meaning that all brain functions for a critter can be housed within a single brain chassis particle.

Inheritence

Not only can we move and reorient copies of segments of particles (or brain components), but we can also morph them by including partial subsets of the attributes and child nodes with the same names, but with different attributes. So only the changes are reflected and the rest of a segment which is used as the "model" for another segment are assumed to be the same.

Inflation

Inflation is a process that happens as a model definition file is loaded. Before the model can be used to construct a critter ("embodiment"), the model must be fleshed out in more explicit detail than is available in the definition file. The main result of inflation is that any segments that use other segments as their models have copies of the originals taken and the explicit modifications applied to the copies. The end result is at least one model in memory for each particle or brain component that will eventually be built.

Embodiment

Embodiment is the end result of all this modeling. A model definition file technically represents a starting point for an entire planet. Once inflation and some related processes are done, an algorithm walks through the entire model tree and constructs the planet as a sort of physical mirror of the model. The model can either be kept to help with study or discarded to recover memory.

Paths

One of the hardest challenges for me to date with this modelling concept is defining a way for models to refer to one another in nontrivial ways. For example, a link must refer to two particles. This is done using a "path". Paths are slash-delimited strings of names of particles (or ".." to mean "up one level from the current node). The names always refer to named models or, in the case of inputs and outputs, at their tail ends, named input or output terminals.

In resolving a path, the starting point from a model is not that model, but its immediate parent. So if a link's "from" path is "LeftArm/Shoulder", that means that we expect a model named "LeftArm" to be a sibling of this link model.

Paths seem deceptively simple, but it's important to be aware of the semantic meaning of each part of a path. What it can refer to depends on the kind of model that is making the reference and the nature of the referent. In the case of links, all parts that aren't "..", except the last, should refer to segment (or body) models. The last one must be a particle model, since a link must ultimately connect two actual particles. Segments don't exist in the physical embodiment.

For input and output models, the semantics for path parts is more complicated. The source path for an input, except for the last two parts, should refer to circuit, segment, or body models. The second to last must refer to a circuit or a particle, and the last part refers to either an input or output terminal. The same rules apply for output models' source paths.

Circuits

Sensor particles have output terminals that can be hooked into to collect information. Motor particles have input terminals that can be hooked into by brain components to effect actions.

A circuit is a model either for an atomic decision-making component -- a finite state machine, for instance -- or a collection of such components or other circuits. When a circuit model does not specify a class, we say it is a "virtual" circuit because it will not be physically embodied. Segment models are treated as virtual circuits, meaning segments can also have virtual input and output models.

Like sensors and motors, each circuit can have its own named input and output terminals. A virtual circuit can also have input and output models, too, even though they will not be physically embodied. Doing so just gives places to indicate that things like sensors, motors, and brains hook to. Those references get resolved down to links among actual terminals.

It's easy to understand that a given input would get its information from some output terminal. By contrast, saying that an input terminal should draw its information from another input is an odd thing to grasp, but it's important to, especially since source paths for inputs offer both options. In fact, this case only happens when one input terminal has its source pointing at one of a virtual circuit's input terminals. It means that the source of the input will actually be whatever the source of that virtual circuit's input is. Conversely, if one of a circuit's input models has as its source a virtual circuit's outputs, that means whatever the source of that virtual output is will ultimately be hooked into by this input.

Outputs have a similarly complicated picture, but in a more limited way. An output model can't have a source path unless it's for a virtual circuit. In that case, it can only have as its source another virtual input or output or a particle or "real" circuit's output terminal.

Following is a table to better illustrate this mess. Each "X" indicates that the type of terminal in the row header (left side) can use as a source the type of terminal in the column header (top).

Sources --->	particle:input	real circuit:input	virtual circuit:input	particle:output	real circuit:output	virtual circuit:output
particle:input				X	X	X
real circuit:input				X	X	X
virtual circuit:input			X	X	X	X
particle:output
real circuit:output
virtual circuit:output			X	X	X	X

You may wonder what the point is of distinguishing between input and output terminals in virtual circuits, since they act the same. It's mainly for consistency and to make it so "users" of circuits can be kept ignorant of whether any given circuit is going to be physically embodied or is really just an assemblage of smaller parts. A circuit can be thought of as a black box to the outside world in this sense.

One final note. When referring a source to a particle or real circuit model, the last part of the path may in some cases potentially refer to either an input or output terminal if that name is used for both an input and an output terminal for that model. This is resolved by preferring outputs as sources for both input and output terminals.

Element Types

planet

• Represents: An entire planet.
• The root of the document.
• Attributes:
  • size: a vector indicating the physical dimensions of the planet's outer box.
• Parents:
  • None
• Children:
  • body

body

• Represents: A single critter that is to be constructed.
• Attributes:
  • name
  • position
  • angle
• Parents:
  • planet
• Children:
  • particle
  • segment
  • link

segment

• Represents: An abstract collection of particles that can be replicated and manipulated as a whole during inflation.
• Attributes:
  • name
  • position
  • angle
• Parents:
  • body
  • segment
• Children:
  • particle
  • input
  • output
  • segment
  • link

particle

• Represents: An actual particle, whose type is determined by the "class" attribute.
• Attributes:
  • name
  • position
  • angle
  • class: Which class to instantiate during embodiment; e.g., "Particle", "ActiveParticle", "Bumper".
  • mass
  • radius
  • color
• Parents:
  • body
  • segment
• Children:
  • input
  • output

link

• Represents: A physical, spring-type link between two embodied particles.
• Attributes:
  • from: Path to one particle to link.
  • to: Path to another particle to link to.
  • strength: Single indicating the strength of the the link.
  • dampening: Single indicating the spring dampening factor.
• Parents:
  • body
  • segment
• Children:
  • None

circuit

• Represents: A physical decision-making component or an abstract collection of such components that can be replicated and manipulated during inflation.
• Attributes:
  • name
  • class: Which brain component class to instantiate during embodiment; e.g., "Fsm", "Olfactor". If blank, this is a virtual circuit and won't be literally embodied.
• Parents:
  • circuit
  • particle (only if class="BrainChassis")
• Children:
  • circuit
  • input
  • output

input

• Represents: An input terminal.
• Attributes:
  • name
  • source
• Parents:
  • circuit
  • particle
• Children:
  • None

output

• Represents: An output terminal.
• Attributes:
  • name
  • source
• Parents:
  • circuit
  • particle
• Children:
  • None

Commonly Used Attributes

name

• Represents: The logical name of a model.
• Data type: String
• Must be unique among its immediate siblings.

position

• Represents: The coordinates of this entity, relative to the parent entity's position.
• Data type: Vector
• Representation: A comma-separated list of ordinates.
• Example: position="100, 500"
• During inflation of the model, these positions get resolved constructively and are reflected in the embodiment of the critter's constituent parts.

angle

• Represents: The angle fo this entity, relative to the parent entity's angle.
• Data type: Single
• During inflation of the model, these angles get resolved constructively and are reflected in the embodiment of the critter's constituent parts.

color

• Represents: A color
• Data type: Color
• Representation: A comma-separated list of RGB components.
• Example: color="255, 0, 0" (red)

source

• Represents: A path to some other input or output terminal, relative to this node's own parent node.
• Data type: Path
• Representation: A slash-delimited path.
• Example: source="../../Brain/Idea/Fsm1/O1"

Copyright © 2010 The Library of Alexandria. All rights reserved. Produced in cooperation with Carnell Information Systems, Inc.