Pattern Match API

I. Requirements from SRI. 

We need from SRI a function that takes as its input the name of a
concept and returns either a handle or path to the .km file that 
contains the definition of the concept. 


II. Function API

The following are the APIs of the functions we will provide SRI.

FUNCTION:	filter-coa-with-pattern
INTERFACE:	(filter-coa-with-pattern <pattern-name> <coa-name>)
DESCRIPTION:	This function is used to filter a COA with a pattern.
INPUT:		<pattern-name> := The name of the pattern.
		<coa-name> := The name of the COA.
OUTPUT:		This function will return the result of the match. NIL is 
		returned if the COA and the pattern did match. If there was 
		a match, the result will be a list of the triples in the COA 
		that matched the pattern. Each triple in the list is of the 
		form
                                
                                (<inst> <rel> <inst>)
                For example,

                                (_Object111 has-part _Object724)
		
		The output uses the same syntax as the .lmaps files to
		allow SHAKEN to directly display the results. 

		If there is an error, the return value is one of the following 
		error codes:

		  0: The .km file that contains <coa-name> could not be opened. 
		     The program will abort.
		  1: The .km file that contains <coa-name> could not be converted 
		     to the internal format used for matching. The program will 
		     abort.
		  2: The .km file that contains <pattern-name> could not be opened. 
		     The program will abort.
		  3: The .km file that contains <pattern-name> could not be converted 
		     to the internal format used for matching. The program will abort.


FUNCTION:  	pattern-match
INTERFACE:	(pattern-match <coa-name> &optional <dimension> <patterns>)
DESCRIPTION:	This function will critique a COA with patterns.
INPUT:		<coa-name> := The COA that is critiqued.
		<dimension> := This is a list of dimensions that the COA 
			will be critiqued on (e.g. '(|Simplicity| |Speed|
			|Efficiency|)). This is an optional parameter. If 
			left unspecified, the COA will be critiqued along
			all the dimensions represented by the critiquing
			patterns.
		<patterns> := This is a list of the names of the patterns 
			that will be used to critique a COA (e.g. 
			'(|Early-Attack| |Dangerous-Terrain|)). A pattern's 
			name is the name that is given by the SME when the
			pattern was authored. This is an optional parameter. 
			If left unspecified, the COA will be critiqued by 
			all the patterns.
OUTPUT:		This function returns the result of the match. This can take 
		two forms. SRI: PLEASE CONSIDER WHICH OF THESE FORMATS YOU 
		PREFER, AND LET US KNOW. WE WILL THEN PROVIDE A MORE DETAILED 
		DESCRIPTION OF THE OUTPUT. The first form is a list of tuples. 
		Each tuple in the list is of the form:
                
                        (<Pattern-Name> <explanation>)
                where
                        <Pattern-Name> := The name of the pattern that
					  matched the COA.	
                        <explanation>  := A list of pair wise matches 
					  between <Pattern-Name> and 
					  the COA.
                
		NIL is returned if there are no matches.
  
                The second format is a tagged file containing the information 
		described above. 

		If there is an error, the return value is one of the following 
		error codes:

		  0: The .km file that contains <coa-name> could not be opened.
                     The program will abort.
		  1: No patterns could be found. The program will abort.
		  2: The rewrite rules could not be loaded. The program 
		     will abort.
		  3: One of the specified dimensions in <dimension> is
		     unknown. The program will abort. 
		  4: One of the patterns specified in <patterns> does
		     not exist. The program will abort. 
		  5: There was an error opening up a pattern's .km file.
		     The program will abort.
		  6: There was an error converting a pattern's .km file
		     to the internal format used for matching. The program 
		     will abort.


FUNCTION:       pattern-match-with-rich-output
INTERFACE:      (pattern-match-with-rich-output <coa-name> &optional <dimension> 
		 <patterns>)
DESCRIPTION:    This function has the same functionality as pattern-match. It
		differs from pattern-match in only one way. The output contains
		additional information such as the critique dimension, score, 
		etc..
INPUT:		Same as pattern-match.
OUTPUT:		This function returns the result of the match. This can take two 
		forms. SRI: PLEASE SEE THE EXAMPLES IN SECTION III OF THESE 2 
		FORMATS, AND TELL US WHICH YOU PREFER. THEN, WE WILL PROVIDE A 
		MORE DETAILED DESCRIPTION. The first form is a list of matches. 
		Each element in the list is of the form:

                        (<Pattern-Name>
                         <critique-contributions>
                         <text-gen>
                         <explanation>)
                
                The individual components are:
                        
                <Pattern-Name> := The name of the pattern.
                <critique-contributions> := A list of tuples of the 
			form (<dimension> <score>) where <dimension> 
			is the critique dimension and <score> is the 
			critique score.
                <text-gen> := This is the instantiated text-gen
                        template associated with the pattern (see
                        storyboard2.ppt for more details regarding
                        how a sme authors text-gen templates).
                <explanation> := This is a list of pair wise matches
                        between the pattern and the COA.

		NIL is returned if there are no matches.

		The second form is a tagged file containing the information 
		described above.

		This function has the same error codes as pattern-match.

III. EXAMPLE

Attack-Enemy.km: 

	(Attack-Enemy has (superclasses (Pattern)))
	(Attack-Enemy now-has (prototypes (_Attack-Enemy111)))

	...

	(_Attack-Enemy111 has
	   (instance-of (Attack-Enemy))	
	   (called ("Attacking the Enemy"))
	   (critique-score (_Critique-Score-Value478))
	   (base (_Attack112)))

	 (_Attack112 has
	   (instance-of (Attack))	
           (agent (_Military-Unit123))   
           (object (_Military-Unit456)))

	 (_Critique-Score-Value478 has
	   (instance-of (Critique-Score-Value))
	   (value ((:pair *+ Resource-Use)))) 

	 (_Military-Unit123 has (instance-of (Military-Unit)))
	 (_Military-Unit456 has (instance-of (Military-Unit)))
     
COA-E.km:     

	(COA-E has (superclasses (COA-for-Attack)))
        (COA-E now-has (prototypes (_COA-E222)))

	....

	(_COA-E222 has
	   (instance-of (COA-E))	
           (subevent (_Attack311)))
                
         (_Attack311 has
	   (instance-of (Attack)) 	
           (agent  (_Tank-Unit555))
           (object (_Artillery789)))
                         
	(_Tank-Unit555 has (instance-of (Tank-Unit)))
	(_Artillery789 has (instance-of (Artillery)))


COA-E can be critique with the following call.

	(pattern-match-with-rich-output "COA-E.km")

The output for the two proposed formats are:

Format1: 
      
       ((|Attack-Enemy|
	 ((|Resource-Use| |*+|))
	 ("The Tank-Unit attacked the Artillery")
	 (((_Attack112 agent _Military-Unit123)
	   (_Attack311 agent _Tank-Unit555))
	  ((_Attack113 object _Military-Unit456)
	   (_Attack311 object _Artillery789))))
       )

Format2:

<patternmatch>
	<patternname>Attack-Enemy</patternname>

	<critiquecriteria>

		<critique dimension=Resource-Use> + </critique>
	  
	</critiquecriteria>

	<question>Did the military unit perform an attacked?</question>

	<description>The Tank-Unit attacked the Artillery</description>

	<explanation>
		<match>
			<patternelement>
			 	<frame>_Attack112</frame> 
				<slot>agent</slot> 
				<value>_Military-Unit123</value>
			</patternelement>
			<coaelement>
				<frame>_Attack311</frame>
				<slot>agent</slot> 
				<value>_Tank-Unit555</value>
			</coaelement>
		</match>

		<match>
                	<patternelement>
				<frame>_Attack113</frame> 
				<slot>object</slot>
				<value>_Military-Unit456</value>
			</patternelement>
                	<coaelement>
				<frame>_Attack311</frame> 
				<slot>object</slot> 
				<value>_Artillery789</value>
			</coaelement>
        	</match>
	</explanation>
</patternmatch>