KOKOPELLI-1

KOKOPELLI

KOKOPELLI-2

Motivations

• A common usage for SPIRITS is to parametrically vary several of the input conditions

– Environment– Sensor bandpass– Sensor location (range, zenith, azimuth)– Engine power settings

• For most variables, SPIRITS can only accept a single input value, not a vector of values

• The processing chain must be rerun for each set of input values– This can easily lead to hundreds or thousands of individual

input files• When we require multiple values for one or more input variables,

we refer to it as a “matrix of cases”

KOKOPELLI-3

Matrix of Cases - Example

• Consider a simple matrix of cases

– Power settings: cruise and full afterburner– Altitude: 15,000 ft and 30,000 ft– Bandpass: LWIR and MWIR– Observer location: 0° and 180° azimuth– Observer range: 1 km and 5 km

• The total matrix contains 25 = 36 cases†

• How many times must you run – TRBEXT? – SIRRM? – Hardbody?

• What if you vary sensor azimuths in 10 ° steps, and then the sun?† We have ignored variables which may implicitly depend on the variables in this matrix. For

instance, one would usually change the Mach number as the engine power changes.

KOKOPELLI-4

Organizing the Workflow

• For the simple matrix of cases presented here, creating the necessary input and output files by hand is a managable, if tedious, task

• As the complexity of a matrix increases, the possibility of user input error increases as well

• Most users are forced to become adept at writing shell scripts to automate their SPIRITS computations– You end up creating a new set of scripts tailored for each

job; the patterns are the same, but the specifics differ

KOKOPELLI-5

Kokopelli Overview

• Kokopelli is a general software tool for defining and executing a matrix of cases

• Developed with funding from Lockheed-Martin MFC• Freely available, but without user support• Cross-platform Graphical User Interface based on the

Qt widget set– Windows, Linux, IRIX, Solaris

• Input variables may be either scalars or vectors• You can loop over variables in a dependent or

independent manner• Determines workflow dependencies and executes

appropriate tools in the appropriate order

KOKOPELLI-6

Workflow Dependence

• Modular system allows software plug-ins for driving each executable code in SPIRITS

• Each module defines its:– variable inputs– file inputs– file outputs

• Kokopelli can then determine the workflow through SPIRITS– Which codes to run and in which order– Current version does not know how to avoid duplicated

efforts, but this feature is under development• Easy to add additional modules

KOKOPELLI-7

KOKOPELLI FEATURES

KOKOPELLI-8

Overall GUI Layout

• List of input variables on the left, grouped into collapsible categories

• Click on a variable to open an input dialog• Have multiple tabbed

dialogs open at once• Menus:

– File– Edit– Execute– Tools– Help

• Buttons to setor revert values

Group

Variable

Status

Value

Looping Values

Units

Tabs

Buttons

KOKOPELLI-9

• Need to easily set up multiple “batch” runs, varying user inputs

• Allow user to vary as many inputs as possible• Allow user to combine different inputs in different ways• Example: vary the sun zenith and azimuth

– Independently, each azimuth looped over for eachzenith (“outer product”)

– In step, changing at the same time (“inner product”)– e.g. simulate sun’s transit vs time

• Variables varying together are called a “group”– Groups can loop independently of other variables or groups

Multiple Run Capability

90

40

20

ZEN

180

45

0

AZM

User’sInput Values

Inner Product (Gang): 3 Cases

90/45

40/45

20/45

90/0

40/0

20/0

90/180

40/180

20/180

Outer Product: 9 Cases

90/180

40/45

20/0

KOKOPELLI-10

Validity/Consistency Checking

• Each input variable has an allowed range

– Stored in separate ASCII XML configuration file• Testing for consistency between variables

– Especially important when looping over variable values– For example to ensure that target is above earth for all input

combinations– User should not have to manually detect problems

• Kokopelli detects problems when variables are set up (before app is run)– Flags the user with status icons– Two choices available for problems:

– Restrict the inputs manually– Ignore problem; at run time, bad runs will be skipped over

KOKOPELLI-11

Physical Units

• Many inputs to SPIRITS and MODTRAN are physical quantities with associated units

• Kokopelli handles unit conversions for a variety of physical types:

Length Time

Angle Speed

Temperature Pressure

Wavelength/wavenumber Extinction• For each quantity several choices are provided

– e.g., meters, feet, miles, kilometers, yards• User may enter a value in any available unit and may then

change the unit to have a conversion performed

KOKOPELLI-12

Saving User Settings – Templates

• Important capability to save current settings and retrieve them later

• A user may use a saved set as future default values• Avoided hard-wiring default values • Most values are saved in a configuration file of user and system

settings– Stored in ASCII XML format– Readable for a user who wishes to edit it

• Attributes of variables saved includes:

Variable name User Label

Data type Display Group

Valid Range Default value

Tooltip text Help text

KOKOPELLI-13

Online Help

• Two types of online help provided on the input variables

• Hold cursor above variable to pop up a short “tool tip”• Click on Help button and then on a variable to display

more information

KOKOPELLI-14

KOKOPELLI CONFIGURATION

KOKOPELLI-15

Configuring Kokopelli

• On first startup Kokopelli asks for the following locations

– SPIRITS root directory– You must tell Kokopelli the location of the SPIRITS distribution

– SPIRITS directory tree must be organized according to the default installation

– Location of your workspace– Your workspace is a private directory where all input and output files

will be created, organized by case name

– Target Configuration Directory– Location where Kokopelli stores its target config files and template files

• If these change for some reason, then you can force a reconfiguration of Kokopelli from its menu

KOKOPELLI-16

Target Configuration Directory

• Contains important configuration files

– Targets (target configuration files)– Bandpass Filters– Templates (contains samples of user settings)– Databases (optional SPIRITS databases not in /spirits/Databases)

• Default location– Unix: ~/.kokopelli (copied from /usr/share/kokopelli)– Windows: “C:\Program Files\Aerodyne Research\Kokopelli”

• Kokopelli is flexible enough to place databases nearly anywhere– Can't open files on a Windows file share unless you map the

share to a drive letter– Recommend to keep them in the SPIRITS Databases directory

KOKOPELLI-17

System Configuration Storage

• Kokopelli configuration information is stored in a system dependent manner

– Linux: ~/.kokopelli-linux– SGI: ~/.kokopelli-sgi– Solaris: ~/.kokopelli-sun– Windows: Windows registry

• This allows you to keep system dependencies separate when your home directory is shared via NFS to different computers

• Stores the paths to executables, and binary database files– Written the first time you run Kokopelli on a platform

KOKOPELLI-18

ADDING NEW TARGETS

KOKOPELLI-19

Defining Targets

• Each target database described to Kokopelli through a target configuration (“cfg”) file

• Specifies wireframe, thermal file, cycle deck, and other static data files• Cycle deck summary information

– Power variables and their ranges– CycleConfig utility can be used to create necessary cycle deck

config entries• Target config files are stored in a special folder

– Windows: “C:\Program Files\Aerodyne Research\Kokopelli\targets”– Unix: “~/.kokopelli/targets”– Kokopelli's target list is built at run time by searching the contents

of this directory for .cfg files

KOKOPELLI-20

Target Config File Format

• Plain text with one Key-Value pair per line

– Format is “key=value”– Embedded whitespace is ignored; empty lines are acceptable– Null values are acceptable (mostly)

• First variable must be dbPath– All subsequent file names are defined relative to this path

– Except the cycleFile variable for the binary engine cycle deck

– If dbPath is a relative path, then it is assumed to be relative to the “Databases” directory in the SPIRITS distribution

• All keys are optional except: dbPath, targetName, wireframeFile, thermalFile and paintFile– For any “real” problem this is insufficient

KOKOPELLI-21

Target Config File Format– Engine Cycle Deck –

$ cycleconfig

Please enter the input binary cycle deck name:Aircraft3-binary.cyc Please enter the output file name:Aircraft3.cfg Finished

• Begin creating a config file by running the cycleconfig utility

• Command line only• Only creates part of the configuration file, the remainder

must be provided by you

KOKOPELLI-22

Cycleconfig Output

Kokopelli Target Config FilecycleFile=Aircraft3-binary.cycengineType=TFINspecialEngineIndex= 0afterburning=YESpwrrtgMin= 23.0pwrrtgMax=127.0pwrrtgBreak= 83.0altitudeMin= 0.0altitudeMax= 15000.0flightmachMin=0.500flightmachMax=1.400powerVars= PWRRTG:[2.300E+01,1.270E+02];TRBTTM:[6.489E+02,1.212E+03]; CMBFUL:[8.070E+02,1.525E+04];ABFUL:[0.000E+00,7.700E+04]; TOTAIN:[6.262E+01,4.839E+02];CORAIN:[2.617E+01,2.283E+02]; CORTMP:[5.814E+02,1.009E+03];CORPRS:[9.976E+00,6.783E+01]; CORMCH:[1.414E-01,3.435E-01];STRTTM:[4.162E+02,1.998E+03]; MIXPRR:[1.143E+00,5.232E+00];NOZARE:[3.081E+00,9.855E+00]; STRARE:[2.777E+00,6.406E+00];STRTPR:[9.883E+00,6.031E+01]; FANRPM:[4.448E+03,1.055E+04];CORPRM:[9.141E+03,1.315E+04]

KOKOPELLI-23

Additional Cfg File Entries

Kokopelli Target Config FiledbPath=ac2r1/Aircraft3targetName=Aircraft3whichFlowCode=SPFengineCycleSource=ENGDengineExitProfileType=TTJEengineHotGasMixing=nozzleMovementOn=OFFmodifyNormalsOn=OFFmovementFile=revs/Aircraft3.movhotmapFile=revs/Aircraft3.hotextFanGeomFile=nozzleGeometryFile=revs/Aircraft3.geowireframeFile=revs/Aircraft3.wirthermalFile=revs/Aircraft3.thrpaintFile=revs/Aircraft3-v2.pntinteractionFile=no_int.intclassificationFile=revs/Aircraft3.clsmodifyNormalsFile=revs/Aircraft3.nrmavionicsBaysExist=NO

subdirectory of database locationor EXTFsee TRBEXT inputssee TRBEXT inputsfor HYBRID profilefor WIREXFORMfor propeller “disks”

for Hardbody thermal options

KOKOPELLI-24

Constructed Paths

• Globally the SPIRITS root directory is /spirits

• Globally SPIRITS Database directory is /spirits/Databases• In file Aircraft3.cfg:

– Variable dPath=ac2r1/Aircraft3– Variable hotmapFile=revs/Aircraft3.hot– The actual path used by Kokopelli for hotmap file is

– /spirits/Databases/ac2r1/Aircraft3/revs/Aircraft3.hot• The same is true for all other files except cycleFile

– The cycle file is a OS-dependent binary file– Kokopelli expects you to follow the SPIRITS convention

– System subdirectories: binsgi, binwin, binlinux, etc.– So cycleFile=Aircraft3-binary.cyc is really (on linux)

/spirits/Databases/ac2r1/Aircraft3/binlinux/Aircraft3-binary.cyc

KOKOPELLI-25

Associated Applications

• SWFView and imTool

• Cross-platform GUIs built using Qt libraries• Feature sets tends to be driven by Aerodyne's needs• Callable from within Kokopelli, or run separately• Owned by Aerodyne Research• Freely available

– No guaranteed support

KOKOPELLI-26

SWFView

KOKOPELLI-27

imTool

KOKOPELLI-28

Obtaining and Using These Tools

• Not required for Kokopelli (but may be called from within it)• Free to use, but unsupported

– Source code available upon request• Primarily developed in-house with multiple funding sources

– Aerodyne IR&D– Army Aviation Advanced Technology Directorate– Army Soldier System Center– Bell Helicopter

• Latest Windows installers are available from ARI’s FTP site– ftp://ftp.aerodyne.com/users/bacon– For other platforms email bacon@aerodyne.com

KOKOPELLI-29

KOKOPELLI LIMITATIONS

KOKOPELLI-30

SPIRITS Features Currently Unsupported in Kokopelli

• All engines are assumed to be identical on a multi-engine target• Paint scheme is obtained from the default thermal file

– If you need a different paint scheme, then you should copy the thermal file and create a new target cfg file to point to that thermal file

• Cannot take advantage of Hardbody's observer looping• Can take limited advantage of Hardbody loop over multiple

bandpasses• Loops are executed in order of definition• Cannot exclude wireframe parts from calculation

KOKOPELLI-31

Kokopelli Near-Term Development

• Actively pushing forward on the development

• Many issues set to be addressed spring and summer 2004– Use of internal Hardbody looping for multiple bands and

observers– Simple method to enter values at regular intervals– Wizard for creating a target config file

• A number of usability “warts” exist that need to be addressed– Saving and reloading a file can reorder the variable tree

KOKOPELLI-32

Kokopelli Long-Term Development

• Better error reporting, diagnostics and recovery • More visualization features

– Preview of Aimpoint and Field of View– Sun/target/observer geometry

• Alternate methods of entering variables– e.g., observer location

• Other signature models put under the same framework– Missiles– Helicopters