A guide to the syntax
Items contained within <>s are things that can be filled in. The text
appearing within <>s is a description of the information there. However,
do not type the <>s.
Underlined items MUST be filled in.
Items contained with []s are completely optional. If you fill the information
in, do not type the []s.
Type parentheses as required by LISP syntax. Any and all parens indicated below
should be used.
Several variables appear as ?x instead of the x one might expect.
This is simply a special syntax used. Please use it!
Refer to examples if confused.
Args: (defCMLConstant <constant>)
Description:
Unknown description. Should not need to use this.
Examples:
(defCMLConstant water) (defCMLConstant liquid) (defCMLConstant gas)
Unknown usage.
When to Use: Not necessary.
Args: (defDimension <name>
[ <dimension expression> ] )
Description:
A dimension is used to describe quantities in a domain theory. For example,
a measurement of an object might be along a height dimension. This means that
it is only applicable for describing the height of an object. The dimensions
are used to separate uses of quantities. In an economics domain, a dimension
might be introduced for currency with units (defined with defUnit)
as dollars.
To create a dimension, specify a name and an optional expression. The expression is used to specify a reduction to other dimensions.
The following dimensions should be defined in any CML environment: time-dimension, length-dimension, temperature-dimension, mass-dimension, luminosity-dimension, charge-dimension, amount-dimension (usually measured in mole), and dimensionless.
Examples:
(defDimension length-dimension)This specifies that there is a dimension of length. It is generic and not reducible.
(defDimension power-dimension (/ work-dimension time-dimension))
The power-dimensoin can be reduced to work divided by time.
When to Use:
Use defDimension when a quantity needs to be described with relation
to some dimension.
Args: (defEntity <name>
[:subclass-of (super-1 ... super-n)]
[:quantities ((quantity-1 <QF Keywords>) ... (quantity-n
<QF Keywords>))]
[:consequences ( (consequence-1) ... (consequence-n) ]
[:documentation <string>]
[:substitutions ((<symbol-1> <form-1>) ... (<symbol-n> <form-n>))]
)
Description:
defEntity is used to specify the properties for a class of objects. An
entity can be understood as a class in standard Object-Oriented style. This
means that entities can subclass other entities. A subclassed entity inherits
all of the properties, quantities of a superclass. Relations that hold for superclasses
also hold for subclasses. However, this relationship works only in one way.
Superclasses do not inherit any information specific to subclasses. Note that
you need not specify subclass relationships in a superclass, but a superclass
must exist if you attempt to subclass it.
To instantiate an instance of an entity, use defUniversalFact or defScenario. If you are subclassing an existing entity, please indicate so. Remeber, the entity must either exist in the domain theory or in the CYC Upper Ontology. If you are working with the Domain Theory Environment(DTE), then you should consult the CYC Upper Ontology to see if you can subclass entities already present there. Please not that the QRG system is NOT case-sensitive. As a result, items in CYC, like VectorInterval, which rely on capitalization to separate the words, are accessed differently. Any term in CYC with a capital letter is expressed as in lower-case form with a dash before the capital letter. Thus, VectorInterval becomes vector-interval.
Next, specify any applicable quantities that describe an instance of the entity. For example, if you are representing a container, you should represent height as a quantitiy. Use the QF keywords to specify type, but note that :=> is not allowed. Next, specify any consequences in the :consequences clause. A consequence is something that holds whenever an instance of the entity is active. Finally, add any :documentation or :substitutions.
Note that defEntity is a special case of defModelFragment. Also note the following special syntax
Examples:
(defEntity container :quantities ((bottom-height :type bottom-height) (top-height :type top-height)) :consequences ((> top-height bottom-height)))
This fragment defines a type of objects "container." This is not a subclass, so it is a top-level entity. That is, it is not part of an existing object hierarchy. There are two quantities, which are themselves instances of entities: bottom-height and top-height. The only consequence is that top-height must be greater than bottom-height. That is, if you have a container whose top is 1 ft high, then the bottom-height should not be greater than it. Such a container would be nonsensical and could not exist.
When to Use:
Use defEntity when declaring a properties of a single object that are
always true. Otherwise, use defModelFragment.
To instantiate an instance of an entity, use defUniversalFact
or defScenario.
Args: (defModelFragment <name>
[:subclass-of (super-1 ... super-n)]
[:participants ((participant-1 [:type type-1]) ... (participant-n [:type type-n]))]
[:conditions ( (<condition-1>) ... (<condition-n>))]
[:quantities ((quantity-1 <QF Keywords>) ... (quantity-n
<QF Keywords>))]
[:attributes ((participant-1 [:type type-1]) ... (participant-n [:type type-n]))]
[:consequences ( (<condition-1>) ... (<condition-n>))]
[:documentation <string>]
[:substitutions ((<symbol-1> <form-1>) ... (<symbol-n> <form-n>))]
)
Description:
defModelFragment is the form at the heart of CML. It is used to define
a class of objects which are described by common static attributes and time-dependent
quantities. It also defines interactions between different entities, the conditions
for those interactions, and any consequences. A model fragment can be understood
as a class in standard Object-Oriented style. This means that it can subclass
other fragment. A subclassed fragment inherits all of the properties, quantities
of a superclass. Relations that hold for superclasses also hold for subclasses.
However, this relationship works only in one way. Superclasses do not inherit
any information specific to subclasses. Note that you need not specify subclass
relationships in a superclass, but a superclass must exist if you attempt to
subclass it.
If you are subclassing an existing fragment, please indicate so in the :subclass clause. Remeber, the entity must either exist in the domain theory or in the CYC Upper Ontology. If you are working with the Domain Theory Environment(DTE), then you should consult the CYC Upper Ontology to see if you can subclass objects already present there. Please not that the QRG system is NOT case-sensitive. As a result, items in CYC, like VectorInterval, which rely on capitalization to separate the words, are accessed differently. Any term in CYC with a capital letter is expressed as in lower-case form with a dash before the capital letter. Thus, VectorInterval becomes vector-interval.
Next specify any participants in the model in the :participants clause. A participant clause indicates what objects interact in a model fragment instance. Use the :quantities Specify any applicable quantities that describe an instance of the entity. For example, if you are representing a container, you should represent height as a quantitiy. Use the QF keywords to specify type, but note that :=> is not allowed. The :attributes clause is currently not used. Specify any consequences in the :consequences clause. A consequence is something that holds whenever an instance of the entity is active. Finally, add any :documentation or :substitutions.
Note that there is a special case of defModelFragment for defining a single object whose properties are always true: defEntity. Also note the following special syntax
Examples:
(defModelFragment heat-flow :subclass-of (physical-process) :participants ((the-src :type thermal-physob) (the-dst :type thermal-physob) (the-path :type heat-path
:conditions ((heat-connection the-path the-src the-dst) (heat-aligned the-path) (> (temperature the-src) (temperature the-dst))) :quantities ((heat-flow-rate :type heat-flow-rate)) :consequences ((Q= heat-flow-rate (- (temperature the-src) (temperature the-dst))) (I- (heat the-src) heat-flow-rate) (I+ (heat the-dst) heat-flow-rate)))
This is model fragment describing heat flow. It is a subclass of physcal-process. This may have been defined in CYC or in the domain theory. There are several participants: the source of the heat, its destination, and the path. There are three conditions. The first is that the relation heat-connection must hold for the-path, the-src, and the-dst. This means that the path must be a heat connection for the source and the destination. If this condition is not met, then the fragment is not active. Moreover, heat-aligned relation must hold for the-path. Finally, the temperature of the-src must be greater than that of the-dst. These relations can be specified using defUniversalFact or defScenario.
Moving on to quantities, the heat-flow-rate can be specified. If you wanted to create an instance of heat flow, you could do something like this:
(defUniversalFact (sample-flow heat-flow)) (defUniversalFact (heat-flow-rate sample-flow fast))
This creates an instance, sample-flow of heat flow and indicates that its heat-flow-rate is "fast." In the case of this fragment, you would not actually want to set the heat-flow-rate like the example shows. This is just an illustration of syntax.
Finally, there are consequences of the model fragment. In this case, the heat-flow-rate is qualitative-equal or Q= to the difference of the-src's temperature and the-dst's temperature. This means, roughly, that the heat-flow-rate of the instantiation of this fragment is the same as the difference of temperature in this fragment. The other consequences indicate that heat is flowing away from the source to the desination.
When to Use:
Use to define a class of objects. However, if you are only defining a single
object whose properties are always true, consider defEntity.
To instantiate an instance of a fragment, use defUniversalFact
or defScenario
Args: (defQuantityFunction<name> (x-1 ... x-n)
[ :=> <implication asentence> ]
[:dimension <dimension expression> ]
[:non-numeric <boolean, default to F> ]
[:piecewise-continusous <boolean, default to F>]
[:step-quantity <boolean, default to F>]
[:count-quantity <boolean, default to F>]
[:documentation <string>] )
Description:
A defQuantityFunction maps a set of inputs into a quantity. A quantity
function associates time-dependent quantities with the objects it describes.
:documentation should contain a description of the function. The rest
of the fields describe the function and can be used by defEntity
and defModelFragment.
Examples:
(defQuantityFunction mass (?x) :=> (physical-object ?x) :dimension mass-dimension)This quantity function specifies the mass of an object. It implies that the object is a physical object and that the dimension of the quantity returned will be the mass dimension. For more information on dimension, consult defDimension. Some more examples of a similar vein follow.
(defQuantityFunction mass-flow-rate (?x)Note that this is a step-quantity.
:=> (mass-flow ?x) :dimension energy-dimension) (defQuantityFunction distance (?p1 ?p2) :=> (and (point ?p1) (point ?p2)) :dimension length-dimension) (defQuantityFunction high-tide-height (?x) :step-quantity t :dimension length-dimension)
(defQuantityFunction people-in-line (?x) :count-quantity t :=> (line-of-people ?x))Note that this is a count-quantity and therefore has no dimension.
(defQuantityFunction stop-light-color (?x) :non-numeric t :=> (and (stop-light ?x) (range (stop-light-color ?x) (setof red green yellow))))Note that the result is non-numeric. It is either red, green, or yellow.
When to Use:
Use defQuantityFunction when a relation that transforms objects into
a quantity is required.
Args: (defRelation <Name> (<x-1> ... <x-n>)
[ :=> <implication asentence> ]
[ :<=> <iff asentence> ]
[:function <boolean, default F> ]
[:time-dependent <boolean, default F>]
[:documentation <string>] )
Description:
defRelation defines a relation between one or more diferent objects.
When a relation holds between a set of objects, the information in the implication
asentence and/or the iff (if and only if) asentence is considered true as well.
In order to specify that certain objects fit in the relation, consult forAll
and the defScenario forms.
Examples:
(defRelation similar-angle (?v1 ?v2) :=> (and (2D-Qvector ?v1) (2D-Qvector ?v2)) :documenation "Two vectors have a similar angle if they are both acute or obtuse.")
This relation creates a similar-angle relation of arity two. That means that two items are needed for the relation. Its implication asentece states that both vectors and 2D-QVectors.
When to Use:
Use defRelation anytime you need to specify some property in a domain
that one or more objects in the domain can hold.
Args: (defScenario <NAME>
[:individuals ( (<ind-1> [:type <type-1]>) ... (<ind-n> [:type
<type-n>]))
[:initially ( (<condition-1>) ... (<condition-n>))]
[:throughout ( (<condition-1>) ... (<condition-n>))]
[:boundary ( (<condition-1>) ... (<condition-n>))]
[:documentation <string>]
[:substitutions ((<symbol-1> <form-1>) ... (<symbol-n> <form-n>))]
)
Description:
defScenario is used to specify a set of conditions that define a particular
system, or scenario. For example, if you have a domain theory that models oil
flow, you might want to create a scenario that specifies some interesting interactions
between different flows. To define a scenario, start by speciying the participating
individuals. This is done with the :individuals clause. This step
must be done or the scenario is empty. All other slots are optional. The :individuals
clause defines what things will participate in the scenario. Create a list of
all individuals that you want to interact. In most cases, you wil ned to specify
what entity (see defEntity) they are instances of.
Next, specify any initial conditions using the :initially clause.
These conditions are the initial setting of the properties (read quantities,
see defEntity) of the individuals or any relations (see
defRelation) that hold. These conditions may change
as events occur in the scenario. Third, specify any throughout conditions
with the :throughout clause . These conditions are properties or relations
that must hold throughout the entire scenario. Fourth, specify any boundary
conditions with the :boundary clause. Boundary conditions specify
what quantities or relations must be true for the predictions made the reasoner
to be interesting. Unlike throughout conditions, boundary condtions must
not be true. Fifth, enter some documentation explaining the scenario with :documenation
clause. Finally, enter any substitutions with the :substitutions clause
. A substitution is a purely semantic substitution defined from one term to
another. All instances of symbol1 in the defScenario description
will be replaced with form1.
Note: Scenarios must take place within the context of a particular domain theory. Therefore, the entity types used and any facts taken advantage of must be accessible from that domain theory.
Examples:
(defScenario on-test :individuals ((proj-1 :type projector) (desk-1 :type desk) (room-1 :type room-ina-construction)) :throughout ((in--cont-generic desk-1 room-1) (on--physical proj-1 desk-1)) :documentation "A projector is on a desk with is in a room.")
This is a simple scenario which instantiates a desk, a projector, and a room. The relation, in--cont-generic holds firk desk-1 and room-1. This means that the desk is in the room. The relation on--physical holds for proj-1 and desk-1. This means the projector is on the desk.
To reason about this scenario in DTE, evaluate the above scenario, and then:
(start-reasoning-session :background-name 'on-test) (is-true? (in--cont-generic desk-1 room-1)) (all-true? (touches desk-1 ?x)) (all-true? (in--cont-generic ?x room-1))
When to Use:
Use defScenario to build a decription of a particular system that you
want to reason about.
Args: (defUnit <name>
[:= <quantity expression>]
[:dimension <dimension expression>] )
Description:
A unit describes a quantity in the domain theory. This function adds new units
and specifies optional conversion and dimension expressions. The optional quantity
expressions indiciates a conversion to a more fundamental unit. If it is absent,
then this unit is considered fundamental. The dimension expression restricts
the unit to specification along that dimension. If no dimension is specified,
the unit will default to the dimension of the unit in the quantity expression,
but it may be better to explicitly state the dimension. A fundamental unit must
have a dimension.
Examples:
(defUnit meter :dimension length-dimension) (defUnit cm := (* 0.1 meter)) (defUnit inch := (* 2.54 cm))The first statement defines meter as a fundamental unit along the length dimension. The second statement defines centimeters and expresses a conversion in the quantitiy expression. This means that the length-dimension is inhereited. Likewise, the third statement defines a unit inch and expresses a conversion to the cm unit. It is along the length-dimension.
When to Use:
Define units whenever appropriate for the domain. For more information on this
topic, please consult the DTE
documenation.
Args: In general: (defUniversalFact &rest rest-of-form &optional
:documentation)
Specifically: (defUniversalFact (<Entity> <New-Instance>)) or
(defUniversalFact (<Quantity> <Entity> <Value))
If Numeric, (defUniversalFact (nvalue (<Quantity> <Entity>) <Value>))
Description:
A UniversalFact is just a fact about something. It is a piece of information
that is true throughout the domain being modeled. defUniversalFact is the facility
for adding information about particulars and instances as opposed to general
entities and classes into a domain theory. It can also be used to assign values
to an entity's quantities. Some examples follow.
(defUniversalFact (substance water)) (defUniversalFact (location water underground)) (defUniversalFact (nvalue (amount water) 5.0) :documenation "5 gallons of water")
The purpose of these examples is simple. In the first case, water is declared
to be a substance. This means there exists a class (defined with defEntity
or part of ontology) called substance. Water is then declared to be an instance
of the substance. Note that the reasoner does not care what name you type in.
"Water" has as much relevance as "retaw." However, take
care not to use a name already in use.
In the second case, a quantity of is assigned to the water. The quantity, location,
must be a quantity specifed within the water Entity or its superclasses. The
value assigned must be within the specification for that quantity. For example,
if the quantity was supposed to be non-numeric, the value should not be 30.5.
The third example shows how to assign a numberic value to a property..
When to Use:
Use defUniversalFact when declaring instances or information about instances
that are needed for the domain theory. For example, if you have a domain theory
involving vectors, it would be worthwhile to represent the x and y axes using
defUniversalFact. However, consider using defScenario
if the information indicates a set of particular initial conditions.
Args: (forAll (x-1 ... x-n)
( => (<condition asentence>)
<implication asentence>))
Description:
Warning: This is part of KIF and can be used for DTE, but is not an official
part of CML.
A forAll statement specifies a simple first-order logical rule. If there
exist any entities that meet the conditions specified by the condition asentence
will cause the implication.
Examples:
(forAll (?x1 ?x2) (=> (and (container ?x1) (container ?x2) (> (height ?x1) (height ?x2)) (> (width ?x1) (width ?x2)) (bigger ?x1 ?x2))
This simple forAll rule says that if ?x1 and ?x2 are containers and the height and width of x1 is greater than x2 then the relation bigger holds for ?x1 and ?x2.
When to Use:
Use forAll when authoring a domain in the DTE and a condition to make
another relation true is necessary.