KIDD_User_manual.pdf

For Official Use Only

(U) KIDD Version 7.0.0 User’s Manual

29 May 2014

DISTRIBUTION STATEMENT C: Distribution authorized to U.S. Government agencies and their contractors for administrative and operational use, 2 November 2011. Refer all other requests for this document to: MDA/ESP, 5224 Martin Road, Redstone Arsenal, AL 35898.

WARNING: This document contains technical data whose export is restricted by the Arms Export Control Act (Title 22, U.S.C., Sec 2751 et seq) or Export Administration Act of 1979, as amended, Title 50, U.S.C., app 2401 et seq.

Violation of these export laws are subject to severe criminal penalties. Disseminate in accordance with provisions of DoD Directive 5230.25.

DESTRUCTION NOTICE: Destroy by any method that will prevent disclosure of contents or reconstruction of document.

This document is unclassified.

For Official Use Only KIDD Version 7.0

For Official Use Only ii

(U) TABLE OF CONTENTS

Page

SECTION 1. (U) Installation AND INTEGRATION ............................................. 1-1

1.1 (U) KIDD Installation ........................................................................ 1-1

1.1.1 (U) Installing on Windows ..................................................... 1-1

1.1.2 (U) Installing on Mac OS X ................................................... 1-3

1.1.3 (U) Installing on Linux .......................................................... 1-3

1.1.4 (U) Installing on Solaris ......................................................... 1-4

1.2 (U) KIDD Kernel Integration ............................................................. 1-5

1.2.1 (U) Windows .......................................................................... 1-5

1.2.2 (U) Other ................................................................................ 1-6

1.3 (U) Sample KIDD Drivers ................................................................. 1-7

1.4 (U) Pre-Generated Target and Interceptor Data Files ........................ 1-8

1.5 (U) iKIDD .......................................................................................... 1-9

1.5.1 (U) Windows .......................................................................... 1-9

1.5.2 (U) Other ................................................................................ 1-9

1.6 (U) Manuals ....................................................................................... 1-9

1.7 (U) KIDD Kernel Assumptions and Limitations ............................. 1-11

SECTION 2. (U) INTERFACE SPECIFICATION ................................................ 2-1

2.1 (U) Structure API ............................................................................... 2-1

2.1.1 (U) Structure API Functions .................................................. 2-2

2.1.2 (U) Structure API Implementation ......................................... 2-9

2.1.3 (U) Structure API Example .................................................. 2-13

2.1.4 (U) KIDD Structure Driver .................................................. 2-14

2.1.5 (U) KIDD NameList Driver ................................................. 2-14

2.2 (U) Subroutine API .......................................................................... 2-16

2.2.1 (U) Subroutine API Functions ............................................. 2-16

2.2.2 (U) Subroutine API Implementation .................................... 2-21

2.2.3 (U) KIDD Subroutine Driver ............................................... 2-21

2.3 (U) KIDD API Comparison ............................................................. 2-23

2.4 (U) Discrete Fragment Arrays ......................................................... 2-25

2.5 (U) KIDD Structure API Specification Change History .................. 2-28

2.6 (U) KIDD Subroutine API Specification Change History ............... 2-30

SECTION 3. (U) INPUT VARIABLE DEFINITIONS .......................................... 3-1

3.1 (U) Variable Changes ........................................................................ 3-1

3.2 (U) Variable Definitions .................................................................... 3-2

3.2.1 (U) Discrete Fragment Options ............................................ 3-13

3.2.2 (U) Material Inputs .............................................................. 3-14

3.2.3 (U) Heavy Fragment Mass Inputs ........................................ 3-15

3.2.4 (U) Gurney Mass Inputs ....................................................... 3-17

For Official Use Only iii

3.2.5 (U) Non-Target Specific Inputs ........................................... 3-18

3.2.6 (U) Default Target Specific Inputs ...................................... 3-19

3.2.7 (U) Target Without a Warhead Inputs ................................. 3-20

3.2.8 (U) Nuclear Warhead Target Inputs .................................... 3-22

3.2.9 (U) Chemical Submunition Warhead Target Inputs ............ 3-23

3.2.10 (U) Bulk Chemical Warhead Target Inputs ......................... 3-24

3.2.11 (U) Unitary HE Warhead Target Inputs ............................... 3-26

3.2.12 (U) Bomblet Warhead Target Inputs ................................... 3-27

3.2.13 (U) Runway Cratering Munition Warhead Target Inputs .... 3-29

3.2.14 (U) Attached Booster Specific Inputs .................................. 3-30

3.2.15 (U) Separated Booster Specific Inputs ................................. 3-32

3.2.16 (U) Random Number Generator Inputs ............................... 3-35

3.2.17 (U) Mass Conservation/Monte Carlo/Multi Thread Inputs . 3-35

3.2.18 (U) Faster Execution ............................................................ 3-37

3.2.19 (U) Lethality Inputs .............................................................. 3-41

3.2.20 (U) Pre-Generated Target Data Files ................................... 3-41

3.2.21 (U) KIDD-PEELS Run Time Interface ................................ 3-45

3.2.22 (U) Discrete Fragment RCS Calculation Options ................ 3-49

3.2.23 (U) Pre-Generated Interceptor Data Files ............................ 3-50

3.2.24 (U) Booster Self-Destruct Option ........................................ 3-52

3.2.25 (U) Impact Geometry Option ............................................... 3-53

3.2.26 (U) Fragment Speeds Based on Atmospheric Density ........ 3-53

3.2.27 (U) KIDD Thermophysical Properties Function .................. 3-56

SECTION 4. (U) OUTPUT VARIABLE DEFINITIONS ...................................... 4-1

4.1 (U) Variable Changes ........................................................................ 4-1

4.2 (U) Variable Definitions .................................................................... 4-2

SECTION 5. (U) INTERACTIVE KIDD................................................................ 5-1

5.1 (U) iKIDD Introduction ..................................................................... 5-1

5.1.1 (U) iKIDD Basics .................................................................. 5-1

5.1.2 (U) Sample Input Sets ............................................................ 5-2

5.1.3 (U) Inputs Help ...................................................................... 5-2

5.1.4 (U) iKIDD Log ...................................................................... 5-3

5.2 (U) iKIDD Inputs ............................................................................... 5-3

5.2.1 (U) General Inputs ................................................................. 5-4

5.2.2 (U) KIDD-PEELS Run Time Interface Option ..................... 5-5

5.2.3 (U) Target Inputs .................................................................... 5-6

5.2.4 (U) Material Composition Lists ............................................. 5-6

5.2.5 (U) Target Data File Option ................................................... 5-7

5.2.6 (U) Booster Inputs .................................................................. 5-8

5.2.7 (U) KV Inputs ........................................................................ 5-9

5.2.8 (U) Interceptor Data File Option ............................................ 5-9

5.2.9 (U) Output Reporting ........................................................... 5-10

For Official Use Only iv

5.2.10 (U) Fragment Bin Lists ........................................................ 5-10

5.2.11 (U) Fragment Bin Generator ................................................ 5-11

5.3 (U) iKIDD Options .......................................................................... 5-12

5.4 (U) iKIDD Plotting .......................................................................... 5-13

5.4.1 (U) Manage Plot Libraries ................................................... 5-14

5.4.2 (U) Backup and Restore Plot Libraries ................................ 5-15

5.4.3 (U) Manage Plot Series ........................................................ 5-15

5.4.4 (U) Adjust Plot Series .......................................................... 5-16

5.4.5 (U) Custom Expressions ...................................................... 5-17

5.4.6 (U) Adjust Plot Settings ....................................................... 5-21

5.4.7 (U) Import External Plot Data .............................................. 5-22

5.4.8 (U) Export a Plot .................................................................. 5-22

5.4.9 (U) Adjust Plot Format ........................................................ 5-22

5.5 (U) iKIDD Output Files ................................................................... 5-23

5.6 (U) iKIDD Known Limitations ........................................................ 5-25

APPENDIX A (U) KIDD STRUCTURE API ARGUMENTS ................................ A-1

APPENDIX B (U) KIDD NAMELIST FORMAT ................................................... B-1

APPENDIX C (U) KIDD_KERNEL SUBROUTINE ARGUMENTS .................... C-1

APPENDIX D (U) KIDD_KERNEL SUBROUTINE CALL .................................. D-1

APPENDIX E (U) KIDD STRUCTURE API INPUT REQUIREMENTS .............. E-1

(U) LIST OF FIGURES

Figure No. Title Page

3-1 (U) Non-Target Specific Inputs ............................................................. 3-18 3-2 (U) Default Target Specific Inputs ........................................................ 3-19 3-3 (U) Target Without A Warhead Inputs .................................................. 3-21 3-4 (U) Nuclear Warhead Target Inputs ...................................................... 3-22 3-5 (U) Generic CSM Model and Input Variables ....................................... 3-23 3-6 (U) Chemical Submunition Warhead Target Inputs .............................. 3-24 3-7 (U) Bulk Chemical Warhead Target Inputs ........................................... 3-25 3-8 (U) Unitary HE Warhead Target Inputs ................................................. 3-26 3-9 (U) Generic Bomblet Model and Input Variables ................................. 3-27 3-10 (U) CB Warhead Target Inputs .............................................................. 3-28 3-11 (U) PB Warhead Target Inputs .............................................................. 3-28 3-12 (U) Generic RCM Model and Input Variables ..................................... 3-29

For Official Use Only v

3-13 (U) RCM Warhead Target Inputs .......................................................... 3-30 3-14 (U) Booster Section Input Variables ...................................................... 3-31 3-15 (U) Attached Booster Specific Inputs .................................................... 3-32 3-16 (U) Separated Booster Specific Inputs ................................................... 3-33 3-17 (U) Separated Booster Section Input Variables ..................................... 3-34 3-18 (U) Fast Run Inputs ................................................................................ 3-40 3-19 (U) Pre-Generated Target Inputs .......................................................... 3-43 3-20 (U) Target Data File Example ................................................................ 3-45 3-21 (U) Example traj.kid File ....................................................................... 3-47 3-22 (U) KIDD-PEELS Run Time Interface Inputs ....................................... 3-48 3-23 (U) Pre-Generated Interceptor Inputs ................................................... 3-51 3-24 (U) Interceptor Data File Example ........................................................ 3-52

(U) LIST OF TABLES

Table No. Title Page

2-1 (U) Summary of Available Structure API Functions ............................... 2-2 2-2 (U) Structure kidd_outputs_write_discrete_and_bin ............................. 2-11 2-3 (U) KIDD NameList Driver File Paths Order ........................................ 2-15 2-4 (U) Summary of Available Subroutine API Functions .......................... 2-16 2-5 (U) Subroutine API Arguments Subdivided in Structure API ............... 2-23 2-6 (U) KIDD 6.8.2 to 6.8.3 Discrete State Array Index Changes .............. 2-31 2-7 (U) KIDD 6.8.2 to 6.8.3 Discrete RCS Array Index Changes ............... 2-32

3-1 (U) KIDD Kernel Input Variables ........................................................... 3-3 3-2 (U) Discrete Fragment Options .............................................................. 3-13 3-3 (U) kidd_ran_rcs_gamma Function Inputs ............................................ 3-50 3-4 (U) kidd_initial_propagation Function Arguments ............................... 3-55 3-5 (U) kidd_thermal_properties Function Arguments ................................ 3-57

4-1 (U) KIDD Kernel Output Variables ......................................................... 4-1 4-2 (U) KIDD Kernel iret Output Definitions ................................................ 4-8

5-1 (U) Current Run Case Argument Variable Reference ........................... 5-19 5-2 (U) Run Case Output Files ..................................................................... 5-24

For Official Use Only 1-1

SECTION 1. (U) INSTALLATION AND INTEGRATION

(U) The Kinetic Impact Debris Distribution (KIDD) Kernel is a subroutine designed to predict the initial debris environments resulting from hit-to-kill missile defense engagements. It is configured for (1) direct integration into other simulations, (2) access through the included drivers, or (3) access through the included Interactive KIDD (iKIDD) graphical interface. Additional information is included in the KIDD Version 7.0 Executive Summary (Reference 1).

(U) Integration may be accomplished through either of two API (Application Programming Interface) implementations: the structure interface, or the conventional subroutine interface. Both interfaces utilize the same KIDD Kernel to determine debris.

(U) Throughout this manual, bold text indicates a file name and italic text indicates a KIDD argument name. The argument names will refer to the conventional Subroutine API argument names unless a subsection specifically references the Structure API. See Appendix A to cross-reference Structure API and Subroutine API arguments.

1.1 (U) KIDD INSTALLATION

(U) The KIDD Kernel and Interactive KIDD (iKIDD) are distributed on a single KIDD installation CD. The CD contains one encrypted install file for each user-requested operating system/platform. This file contains the KIDD Kernel libraries, iKIDD (if applicable), drivers, examples, manuals, and unclassified target data.

1.1.1 (U) INSTALLING ON WINDOWS

1. (U) Insert the KIDD installation CD into a drive capable of reading CDs.

2. (U) If Windows is configured to auto-run CDs as normal, the KIDD installer should automatically open. If it does not, open a window to the drive and double-click the KIDD_Setup icon to begin installation.

3. (U) A welcome window will display. From there, follow the on-screen instructions.

Unclassified

For Official Use Only 1-2

4. (U) When prompted, enter the Name, Organization and Serial Number that was provided.

5. (U) Installing for Current user only will install KIDD within the user’s Documents folder unless directed otherwise.

6. (U) Installing for All users will install KIDD within the main Program Files folder unless directed otherwise. This will require administrative privileges.

7. (U) An optional custom setup is available for those wishing to install only certain KIDD product features.

8. (U) When the installation has completed, press the Finish button to exit.

(FOUO) The KIDD installer by default will create a KIDD700 folder within the main Program Files folder unless directed otherwise. The installer places the following within the installed folder:

• Drivers folder

• iKIDD folder

• KIDD_Kernel_Library folder

• CVF_Calling_Convention folder

• kiddk700_x32_cvf.dll

• kiddk700_x32_cvf.lib

• kiddk700_x64_cvf.dll

• kiddk700_x64_cvf.lib

• kiddk700_x32.dll

• kiddk700_x32.lib

• kiddk700_x64.dll

• kiddk700_x64.lib

• readme_KIDD_Kernel.txt

• KIDD_Support_Files folder

• Manuals folder

(U) Throughout this manual, boldface serif text within a paragraph indicates a specific folder name or a file name.

Unclassified

For Official Use Only 1-3

1.1.2 (U) INSTALLING ON MAC OS X

1. (U) Insert the KIDD installation CD into a drive capable of reading CDs.

2. (U) Open a window to the drive and double-click the KIDD_for_Mac_OS_X folder.

3. (U) Double-click the KIDD700.dmg icon.

4. (U) When prompted, enter the decryption password that was provided.

5. (U) Open a window to the mounted image.

6. (U) Copy the KIDD700 folder to the desired destination to install. (The

Applications folder or the user’s home folder is recommended.)

(FOUO) The KIDD700 folder will contain the following:

• Drivers folder

• iKIDD folder

• KIDD_Kernel_Library folder

• libKIDDK700_x32.a

• libKIDDK700_x64.a

• readme_KIDD_Kernel.txt

1.1.3 (U) INSTALLING ON LINUX

2. (U) Open a window to the drive and double-click the KIDD_for_Linux folder.

3. (U) Copy the KIDD700.zip file to the desired destination for the installation.

(The user’s home folder is recommended.)

4. (U) Open a terminal to the selected destination folder.

5. (U) Enter unzip KIDD700

6. (U) When prompted, enter the decryption password that was provided.

7. (U) Enter tar –xvf KIDD700.tar

(FOUO) The KIDD700 folder will contain the following:

• Drivers folder

• KIDD_Kernel_Library folder

• gfortran folder

• libKIDDK700_x32_gcc41.a

• libKIDDK700_x32_gcc44.a

• libKIDDK700_x64_gcc41.a

• libKIDDK700_x64_gcc44.a

• libKIDDK700_x32.a

• libKIDDK700_x64.a

• readme_KIDD_Kernel.txt

For Official Use Only 1-4

1.1.4 (U) INSTALLING ON SOLARIS

2. (U) Open a window to the drive and open the KIDD_for_Solaris.

3. (U) Copy the kidd700.crypt file to the desired destination for the installation.

The user’s home directory is recommended.

4. (U) Open a terminal to the selected destination directory.

5. (U) Enter crypt <kidd700.crypt> KIDD700.tar

6. (U) When prompted, enter the decryption password that was provided.

7. (U) Enter tar –xvf KIDD700.tar. If this results in a checksum error, an invalid decryption password was entered. Repeat steps 5 through 7.

(FOUO) The KIDD700 directory will contain the following:

• Drivers directory

• KIDD_Kernel_Library directory

• libKIDDK700_x32.a

• libKIDDK700_x64.a

• readme_KIDD_Kernel.txt

• KIDD_Support_Files directory

• Manuals directory

For Official Use Only 1-5

1.2 (U) KIDD KERNEL INTEGRATION

(U) The KIDD Kernel library includes all of the KIDD Kernel, approximately

35,000 lines. This library contains two different APIs: the structure interface, and the conventional subroutine interface. The structure interface argument names are more descriptive and structured than the conventional subroutine argument names. Both interfaces utilize the same KIDD Kernel to calculate debris.

(FOUO) The readme_KIDD_Kernel.txt file, located within the KIDD_Kernel_Library folder, lists what version operating system and compiler were used to create the KIDD library as well as linking instructions. This file may also contain additional updated information generated after this manual was published.

1.2.1 (U) WINDOWS

(FOUO) The KIDD Kernel library is supplied as an x86-32-bit

(kiddk700_x32.dll) and an x86-64-bit (kiddk700_x64.dll) dynamically linkable library (DLL) for Windows. Projects in compilers like Microsoft Visual Studio should be linked to the accompanying library (.lib) file to access the KIDD Kernel functions. For example, to use the kiddk700_x64.dll, the kiddk700_x64.lib file would need to be linked. The DLL will be referenced when the compiled program runs. The DLL should be copied into the same directory as the compiled program, or it may be copied into a proper path for DLLs such as the WINDOWS\system32 folder to make the library available to all projects. Note that some GNU-based linkers prefer instead to be linked directly to the DLL. Refer to the readme_KIDD_Kernel.txt file for more details on compilation and linking.

(FOUO) The kiddk700_x32 and kiddk700_x64 dynamic libraries were created using the default external procedure options for Intel Visual Fortran and need to be referenced using the “C by Reference” calling convention. The following external procedure options should be used when linking to these libraries:

- Calling Convention = C, REFERENCE (/iface:cref)

- String Length Argument Passing = After All Arguments (/iface:nomixed-str-len-arg)

- Append Underscore to External Names = No (/assume:nounderscore)

- Name Case Interpretation = Lower Case or As-Is (/names:lowercase or /names:as_is)

(FOUO) The kiddk700_x32_cvf and kiddk700_x64_cvf dynamic library was created using the default external procedure options for Compaq/Digital Visual Fortran and are Compaq and Powerstation compatible. They need to be referenced using the “STDCALL by Reference” argument-passing convention. The following external procedure options should be used when linking to this library:

- Calling Convention = CVF (/iface:cvf)

- String Length Argument Passing = After Each String Argument (/iface:mixed-str-len-arg)

- Append Underscore to External Names = No (/assume:nounderscore)

For Official Use Only 1-6

- Name Case Interpretation = Lower Case or As-Is (/names:lowercase or /names:as_is)

1.2.2 (U) OTHER

(U) The KIDD Kernel library for Mac OS X, Linux, and Solaris is supplied as a

32-bit and 64-bit static link library. The library may be copied into desired project folders or it may be copied to /lib, /usr/lib, or /usr/local/lib directory to make the library available to all projects. The procedure for linking depends on the user’s development environment. The following external procedure options should be used when linking:

- Append Underscore to External Names = No (-assume nounderscore)

- Name Case Interpretation = Lower Case or As-Is (-names lowercase or -names as_is)

(FOUO) The library must be linked to make the KIDD functions available. Refer to the readme_KIDD_Kernel.txt file for more details on compilation.

(FOUO) Although the Linux gcc based KIDD libraries may be put into a shared library, the KIDD development team does not recommend this. The KIDD library will not exploit the primary advantages of a shared library, but it will be vulnerable to the disadvantages. Only if the framework of the application linking to KIDD is required to have shared libraries or a no-recompile plug-in architecture, should a shared library be needed.

(FOUO) The gfortran/gcc based KIDD libraries ending in "_gcc41.a" and

"_gcc44.a" are compiled with the -fPIC option and can be put into a shared library. Refer to the readme_KIDD_Kernel.txt file for an example of creating a shared library from the supplied gfortran/gcc based libraries.

(FOUO) Advantages of a shared library not exploited by the KIDD library:

• Memory savings: The KIDD library takes a very small memory footprint of about 2 MB when loaded. All KIDD arguments (structure and discrete fragment arrays)

Resolving “unresolved external symbol” errors:

• Make sure that if the x32 library is linked to a project, that the project is set to build x32

• Make sure that if the x64 library is linked to a project, that the project is set to build x64

• When using Microsoft Visual Studio link to the appropriate .lib

• When using a GNU-based linker try linking directly to the appropriate .dll

• Check “Calling Convention”, “Append Underscore”, and “Names Case” options

• If using a compiler or project that requires uppercase external function names, an uppercase KIDD_KERNEL_UC call aliased internally to kidd_kernel may be used.

For Official Use Only 1-7 are allocated by the user. During runtime the memory footprint of the KIDD library will stay at about 2 MB since the KIDD library internally allocates very little memory above the memory already allocated/owned by the user's thread.

About 316 KB of memory would be allocated by the user per 1000 discrete fragments (31 MB for 100,000 fragments). Plus an additional 70 KB per 1000 discrete fragments multiplied by the # of wavelengths if any.

• Load-time savings: Unlike system and utility type libraries, rarely will there be more than one application using the KIDD library running simultaneously in a simulation environment where memory usage/speed might be critical. And for speed critical simulations, the libraries should be loaded at initialization, not at time of call, and would never be unloaded.

• Dynamic extensibility (plug-ins): Capabilities added with each new version of KIDD change the API. Although the Structure API reduces the likelihood of code modification being required, a recompile will certainly still be required for each new version of KIDD.

(FOUO) Disadvantages of a shared library to which the KIDD library will be vulnerable:

• Version conflicts. Even more problematic if multiple codes are using KIDD.

• Interface errors at runtime. These may not fail gracefully, making debugging more difficult.

• Additional procedures imposed for managing the libraries and versioning.

1.3 (U) SAMPLE KIDD DRIVERS

(FOUO) Sample KIDD drivers are located within the Drivers directory inside the installed KIDD directory. Drivers for C and Fortran are included. Examples for both the Structure API and the conventional Subroutine API are given.

(FOUO) These are provided as an example for building interfaces with other codes, but can be used for stand-alone KIDD console runs as well. Appendix A shows the KIDD Structure API argument types and dimensions. Appendix C shows the kidd_kernel Subroutine API argument types and dimensions in the order they appear in the subroutine call.

(FOUO) The KIDD_NameList_Driver mimics basic iKIDD functionality in a command line setting. Both the C++ and Fortran 90 driver load inputs from a KIDD NameList (KNL) file, call KIDD, and write results to files. The namelist input file can be created using iKIDD or the kidd_inputs_save_all_to_knl function. See Appendix B for an example namelist.

For Official Use Only 1-8

1.4 (U) PRE-GENERATED TARGET AND INTERCEPTOR DATA FILES

(FOUO) KIDD target and interceptor data are contained within the

KIDD_Support_Files directory (folder). This directory may be relocated and/or renamed if desired. However, the filenames and directory structure within this directory must not be modified. If the KIDD_Support_Files directory is relocated and/or renamed, then for iKIDD to access the target data, the new directory path must be assigned to iKIDD. This can be set in iKIDD’s Options (Preferences on Mac OS X) window.

(U) Unclassified generic targets, unclassified test targets (if approved), and a generic interceptor are installed as part of the standard KIDD installation.

(FOUO) Test and threat target data at higher classification levels (Secret, Secret//NOFORN, Secret//RD//NOFORN//CNWDI) are provided separately to KIDD users based on a certified need-to-know and appropriate approvals. Note that additional target data distributed at a given classification level will also include target data at lower classification levels (i.e., a Secret//NOFORN release will include Secret files).

(FOUO) To install additional target data, copy the Target Data Files (*.tdf) into the 700_Target_Data directory. If a file already exists, replace the file with the newer version. Do not rename any files or folders. The target data installation CD contains more detailed installation instructions as required.

(FOUO) The KIDD Version 7.0 Targets Manuals, Volume I (Reference 8) and

Volume II (if approved, Reference 9), are installed in the Manuals folder as part of the standard KIDD installation. Volumes III through V (References 10 through 12), are included with the additional target data release at each of the higher classification levels.

(FOUO) Interceptor data may be provided separately to KIDD users based on appropriate approvals. To install additional interceptor data, copy the Interceptor Data Files (*.idf) into the 700_Interceptor_Data directory. If a file already exists, replace the file with the newer version. Do not rename any files or folders. The interceptor data installation CD contains more detailed installation instructions if required. Note that v6.8.2 and v6.8.3 Interceptor Data Files can be used in v7.0 by copying them into the 700_Interceptor_Data directory.

For Official Use Only 1-9

1.5 (U) iKIDD

1.5.1 (U) WINDOWS

(U) iKIDD for Windows requires Windows 2000 or later. The KIDD installer places a shortcut to iKIDD in a “KIDD 7.0” menu under the Windows “Start” Programs menu. Use the Windows “Add/Remove Programs” Control Panel to optionally uninstall an older version of KIDD.

1.5.2 (U) OTHER

(U) iKIDD for Mac OS X requires OS X 10.5 or later (Intel 64-bit only). iKIDD does not support Linux at this time. Planned future upgrades include support for x86-based Linux distributions with GTK+. There are no plans to support Solaris OS.

1.6 (U) MANUALS

(U) The Manuals folder contains the following files:

• CLMRequirementsForm.dot

• KIDD_ChangeRequest.dot

• KIDDAPISpec700.pdf

• KIDDBOCI700.pdf

• KIDDExec700.pdf

• KIDDTargets700Vol_I.pdf

• KIDDTargets700Vol_II.pdf (if approved)

• KIDDUser700.pdf

(U) Interface Specification (KIDDAPISpec700.pdf), Basis of Confidence Volume I (KIDDBOCI700.pdf), Executive Summary (KIDDExec700.pdf), and User’s Manual (KIDDUser700.pdf) are included as PDF files for use with Adobe Acrobat reader or equivalent software. The Interface Specification is identical to this manual’s Section 2 and appendixes. The Executive Summary provides a top-level overview of the KIDD model capabilities as well as the change history for the model. This User’s Manual contains information needed to install and run the KIDD Kernel and iKIDD.

(FOUO) The KIDD Version 7.0 Targets Manuals are included as PDF files and are divided into five separate volumes:

• Volume I: Contains generic targets [FOUO]

• Volume II: Contains ballistic missile test targets [FOUO]

• Volume III: Contains classified Secret targets

• Volume IV: Contains classified Secret//NOFORN targets

• Volume V: Contains classified Secret//RestrictedData//NOFORN//CNWDI targets

For Official Use Only 1-10

(FOUO) Each Targets Manual Volume provides information relevant to the creation of pre-generated target data available for use in KIDD. Volume I (KIDDTargets700Vol_I.pdf) addresses generic unclassified targets and is part of the standard KIDD release to all users. Volume II (KIDDTargets700Vol_II.pdf) addresses unclassified test targets. Volumes III through V (KIDDTargets700Vol_III.pdf, KIDDTargets700Vol_IV.pdf, and KIDDTargets700Vol_V.pdf) address threat and test targets at the classification level of the targets contained within. Volumes III through V are released with their associated target data files to users based on a certified need-to-know and appropriate approvals, and must be manually installed.

(U) The Microsoft Word template files, CLMRequirementsForm.dot and KIDD_ChangeRequest.dot can be used to request special compilation options (e.g., optimization), support for other platforms/operating systems, software modifications, or new capabilities. The Executing Agent will collect and consolidate all such requests for use in future upgrades or enhancements to the model.

For Official Use Only 1-11

1.7 (U) KIDD KERNEL ASSUMPTIONS AND LIMITATIONS

(FOUO) Major assumptions and limitations of the KIDD Kernel include:

• Hit-to-kill engagements

– Lethal or non-lethal damage (bulk and unitary warheads)

– Fractional lethality (submunition and bomblet warheads)

• Ballistic missile targets

– No warhead:

o Flight test targets o Fragments o RSO (satellite) o Chaff o Target 10/11 (refer to KIDD Target Manual Vol IV) o Decoy or jammer

– Nuclear warhead (long and short range)

– Chemical warhead (bulk, canister submunitions, bomblets)

– High explosive warheads (unitary blast warheads)

– Agents of biological origin (ABO) warhead (powder bomblets)

– Runway Cratering Munition (RCM) warhead (high explosive submunitions)

– Attached booster stage (optional for any warhead type)

– Booster without attached RV (non-lethal object)

– Based on currently available test data, the chemical bomblet and powder bomblet models are identical.

• Interceptors

– Mass greater than 1 percent of target mass for targets with a warhead, flight targets, and boosters

– Closing speed greater than 1 km/s and less than 10 km/s

• Materials

– Metals (aluminum, steel, uranium, copper, tungsten, beryllium, titanium)

– Non-metals (silica phenolic, fiberglass, foam, plastic, rubber, carbon)

(FOUO) The interceptor assumptions above are based on the existing database upon which the KIDD models are based. It is recommended to stay within these limits, but the code is not explicitly constrained to these values.

For Official Use Only 2-1

SECTION 2. (U) INTERFACE SPECIFICATION

(FOUO) The KIDD API consists of two different implementations. A structure interface kidd_calculate_debris is callable from C, C++ or Fortran 90 or later. A conventional subroutine interface kidd_kernel is callable from C, C++ or Fortran 77 or later. The structure interface argument names are more descriptive and structured than the conventional subroutine interface argument names. Both interfaces utilize the same KIDD Kernel to calculate debris.

(FOUO) All array arguments within the KIDD API are one-base indexed and this documentation references them as so. For example, the first valid iret array element index would be iret(1) if one-based indexed but would be referenced from C zero-based array indexing as iret(0). So a Report Flag 3 would be reported as an iret(2) in C. The KIDD Structure API contains "KIDD array element index constants" that can be used to clarify discrete array references.

2.1 (U) STRUCTURE API

(FOUO) The structure interface requires inclusion of the KIDD Structure API file to define the API, kidd_structure_api.h for C and C++ or kidd_structure_api.f90 for Fortran. The API will type and dimension KIDD arguments (Appendix A) and constants.

It also provides functions to load and save inputs to a KIDD NameList (KNL) file in standard Fortran namelist format. The structure interface input argument naming convention is consistent with the KIDD NameList (KNL) file format (Appendix B).

(U) The KIDD Structure API file defines:

- Functions to load and save inputs to a KIDD NameList (KNL) file

- Functions to write outputs

- Functions to copy inputs between structures

- Constants that define input settings and array element indexes

(FOUO) Refer to KIDD_Structure_Driver.cpp & KIDD_Structure_Driver.f90 included in the Drivers directory for several situational examples using various Structure API functions.

(U) Within this subsection, italic text indicates a KIDD Structure API argument. See Appendix A to cross-reference to KIDD Subroutine API arguments.

For Official Use Only 2-2

2.1.1 (U) STRUCTURE API FUNCTIONS

(FOUO) Table 2-1 lists structure API functions and their signatures. Structure functions that return a non-zero on failure will populate the KIDD event structure argument kidd_event.extra.error_description with a summary of the failure.

Table 2-1. (U) Summary of Available Structure API Functions

Structure API Function Name Signature int kidd_calculate_debris ByRef kidd_event_structure, ByRef float, ByRef float int kidd_set_fragment_maximum_to_goal ByRef kidd_event_structure int kidd_inputs_load_all_from_knl ByRef kidd_event_structure, ByRef char*, ByVal int int kidd_inputs_load_target_from_knl ByRef kidd_event_structure, ByRef char*, ByVal int int kidd_inputs_load_kv_from_knl ByRef kidd_event_structure, ByRef char*, ByVal int int kidd_inputs_load_target_from_tdf ByRef kidd_event_structure, ByRef char*, ByVal int int kidd_inputs_preload_kv_from_idf ByRef kidd_event_structure, ByRef char*, ByVal int int kidd_inputs_save_all_to_knl ByRef kidd_event_structure, ByRef char*, ByVal int int kidd_inputs_save_target_to_knl ByRef kidd_event_structure, ByRef char*, ByVal int int kidd_inputs_save_kv_to_knl ByRef kidd_event_structure, ByRef char*, ByVal int int kidd_inputs_copy_all_from_structure ByRef kidd_event_structure dst, ByRef kidd_event_structure src int kidd_inputs_copy_target_from_structure ByRef kidd_event_structure dst, ByRef kidd_event_structure src int kidd_inputs_copy_kv_from_structure ByRef kidd_event_structure dst, ByRef kidd_event_structure src int kidd_inputs_populate_with_generic ByRef kidd_event_structure int kidd_inputs_populate_with_zero ByRef kidd_event_structure int kidd_outputs_write_to_file ByRef kidd_event_structure, ByRef char*, ByVal int int kidd_outputs_write_bins_to_files ByRef kidd_event_structure, ByRef kidd_outputs_write_discrete_and_bin int kidd_outputs_write_discrete_to_files ByRef kidd_event_structure, ByRef kidd_outputs_write_discrete_and_bin, ByRef float, ByRef float int kidd_print_run_summary ByRef kidd_event_structure int kidd_write_run_summary ByRef kidd_event_structure, ByRef char*, ByVal int int kidd_report_flag_description ByRef int*, ByRef char[kiddp_max_str_len] int kidd_structure_api_version n/a int kidd_verify_structure_interface ByRef kidd_event_structure int kidd_version n/a float kidd_ran_rcs_gamma ByRef int*, ByRef int*, ByRef int*, ByRef int*, ByRef float*, ByRef float*, ByRef float*, ByRef int* int kidd_thermal_properties ByRef int*, ByRef float*, ByRef float *, ByRef float*, ByRef float*, ByRef float*, ByRef int*, ByRef float*, ByRef float*, ByRef float*, ByRef float* int kidd_initial_propagation ByRef float*, ByRef float*, ByRef float*, ByRef float*, ByRef int*, ByRef float*, ByRef float*, ByRef float*, ByRef float*

(FOUO) Fortran users should not include the final argument ByVal int preceded by a ByRef char*. For example, if fPath were defined as a string, the C call would be i = kidd_inputs_load_all_from_knl(&kidd_event, fPath, strlen(fPath))

While the Fortran call would look like i = kidd_inputs_load_all_from_knl(kidd_event, fPath)

For Official Use Only 2-3 int kidd_calculate_debris(kidd_event_structure* ke, float* discrete_state, float* discrete_rcs);

Purpose: Calculate debris based on the input portion of the KIDD event structure and populate the output argument portion of the event structure and the discrete fragment State and RCS arrays with the calculated results. The discrete arrays must be allocated before calling this function. Refer to Section 2.4 for specifics on how to allocate and reference these arrays.

Args: ke : ByRef : KIDD event - all inputs and outputs of a KIDD Kernel call state : ByRef : Output array of KIDD output Discrete Fragment State by vehicle rcs : ByRef : Output array of KIDD output Discrete Fragment RCS by vehicle Returns: 0 = kiddc_run_completed when no errors or warnings are reported 1 = kiddc_run_failed when a fatal error is reported 2 = kiddc_run_error when an error is reported but not a fatal error 3 = kiddc_run_warning when a warning is reported but no error A summary of the failure will be written to kidd_event.extra.error_description.

int kidd_set_fragment_maximum_to_goal(kidd_event_structure* ke);

Purpose: Perform a speed optimized run to determine the number of discrete fragments that would be generated based on the inputs and set ke.in.o_discrete_fragment_maximum to that fragment goal. No output is populated. The discrete arrays should then be allocated based on this maximum before calling kidd_calculate_debris.

Returns: 0 = kiddc_run_completed, 1 = kiddc_run_failed (fatal error occurred) 2 = kiddc_run_error, 3 = kiddc_run_warning A summary of the failure will be written to kidd_event.extra.error_description.

For Official Use Only int kidd_inputs_load_all_from_knl(kidd_event_structure* ke, const char* path, int length);

Purpose: Populate all inputs of a KIDD event structure by reading them from a KIDD NameList

(KNL) file. See Appendix E for inputs affected by variant functions.

Args: ke : ByRef : KIDD event - all inputs and outputs of a KIDD Kernel call path : ByRef : Input complete path to the KNL file to load length : ByVal : Input path string length (omit in Fortran) Returns: 0 = kiddc_result_success, 1 = kiddc_result_fail On failure, some inputs may still be modified. See Section 2.1.2.

Variants: kidd_inputs_load_target_from_knl: Populate Target Definition only kidd_inputs_load_kv_from_knl: Populate KV Definition only

For Official Use Only 2-4 int kidd_inputs_load_target_from_tdf(kidd_event_structure* ke, const char* name, int length);

Purpose: Populate only Target Definition inputs of a KIDD event structure by reading them from a KIDD Target Data File (TDF). See Appendix E for inputs affected.

NOTE: This function first requires that ke.in.g_kidd_support_files_dir_path be set to the pathname to the KIDD_Support_Files directory.

Args: ke : ByRef : KIDD event - all inputs and outputs of a KIDD Kernel call name : ByRef : Input target alias name length : ByVal : Input name string length (omit in Fortran) Returns: 0 = kiddc_result_success, 1 = kiddc_result_fail On failure, no target inputs will be modified and data stream will be blank.

A summary of the failure will be written to kidd_event.extra.error_description.

For Official Use Only int kidd_inputs_preload_kv_from_idf(kidd_event_structure* ke, const char* name, int length);

Purpose: Preload an encrypted data stream from a KIDD Interceptor Data File (IDF) and store the data stream within the structure. The ke.in.kv_component_damage_flag_lethal and ke.in.kv_component_damage_flag_non_lethal inputs will be populated and editing is allowed, but not recommended unless specific knowledge about the impact geometry is available. The remaining KV Definition inputs will be set to -99. See Appendix E for inputs affected. When kidd_calculate_debris is called, KIDD will use the KV damage flags and the remaining KV Definition inputs from the data stream for KV Definition input. Arguments defining the KV will return -99.

Note: This function sets a flag within the event structure ke.extra.idf_stream_flag = 1.

To get a KIDD event structure to use standard KIDD KV inputs, call the load or copy function with that event structure.

NOTE: This function first requires that ke.in.g_kidd_support_files_dir_path be set to the pathname to the KIDD_Support_Files directory.

Args: ke : ByRef : KIDD event - all inputs and outputs of a KIDD Kernel call name : ByRef : Input interceptor alias name length : ByVal : Input name string length (omit in Fortran) Returns: 0 = kiddc_result_success, 1 = kiddc_result_fail On failure, no kv inputs will be modified and data stream will be blank.

For Official Use Only 2-5 int kidd_inputs_save_all_to_knl(kidd_event_structure* ke, const char* path, int length);

Purpose: Write all inputs of a KIDD event structure to a KIDD NameList (KNL) file. See

Appendix E for inputs affected by variant functions.

Args: ke : ByRef : KIDD event - all inputs and outputs of a KIDD Kernel call path : ByRef : Input complete path to the KNL file to write length : ByVal : Input path string length (omit in Fortran) Returns: 0 = kiddc_result_success, 1 = kiddc_result_fail Variants: kidd_inputs_save_target_to_knl: Write Target Definition only kidd_inputs_save_kv_to_knl: Write KV Definition only

For Official Use Only int kidd_inputs_copy_all_from_structure

(kidd_event_structure* dst, kidd_event_structure* src);

Purpose: Copy inputs to one KIDD event structure from another. See Appendix E for inputs affected by variant functions.

Args: dst : ByRef : destination KIDD event to copy to src : ByRef : source KIDD event from which to copy inputs Returns: 0 = kiddc_result_success, 1 = kiddc_result_fail Variants: kidd_inputs_copy_target_from_structure: Copy just Target Definition kidd_inputs_copy_kv_from_structure: Copy KV just Definition int kidd_inputs_populate_with_generic(kidd_event_structure* ke);

Purpose: Populate all inputs of a KIDD event structure using typical run options and generic

Target and KV inputs. The values are identical to those in a default “Untitled” iKIDD input set which are based on inputs in the sample driver, KIDD_Subroutine_Driver.

Args: ke : ByRef : KIDD event - all inputs and outputs of a KIDD Kernel call Returns: 0 = kiddc_result_success, 1 = kiddc_result_fail int kidd_inputs_populate_with_zero(kidd_event_structure* ke);

Purpose: Populate all inputs of a KIDD event structure with zero.

Args: ke : ByRef : KIDD event - all inputs and outputs of a KIDD Kernel call

For Official Use Only 2-6 int kidd_outputs_write_to_file(kidd_event_structure* ke, Purpose: Write outputs of a KIDD event structure to a standard namelist file. The event structure does not include the discrete fragment State and RCS arrays. Use kidd_outputs_write_discrete_to_files to write these arrays.

Args: ke : ByRef : KIDD event - all inputs and outputs of a KIDD Kernel call path : ByRef : Input complete path to the namelist file to write length : ByVal : Input path string length (omit in Fortran) int kidd_outputs_write_bins_to_files(kidd_event_structure* ke, kidd_outputs_write_discrete_and_bin* kow);

Purpose: Write bin output arrays by bin type to tab-delimited text files. If kow.state_element_order = 0 defaults will be set. See Section 2.1.2.

Args: ke : ByRef : KIDD event - all inputs and outputs of a KIDD Kernel call kow : ByRef : Input structure of options and file paths required for function int kidd_outputs_write_discrete_to_files(kidd_event_structure* ke, kidd_outputs_write_discrete_and_bin* kow, float* discrete_state, float* discrete_rcs);

Purpose: Write discrete fragment State and RCS arrays by vehicle to tab-delimited text files. If kow.state_element_order = 0 defaults will be set. See Section 2.1.2. The discrete arrays must be allocated before calling this function. Refer to Section 2.4 for specifics on how to allocate and reference these arrays.

Args: ke : ByRef : KIDD event - all inputs and outputs of a KIDD Kernel call kow : ByRef : Input structure of options and file paths required for function state : ByRef : Input array of KIDD output Discrete Fragment State by vehicle rcs : ByRef : Input array of KIDD output Discrete Fragment RCS by vehicle

For Official Use Only 2-7 int kidd_print_run_summary(kidd_event_structure* ke);

Purpose: Print a text summary of the KIDD run (Warnings, Errors, Fragment Goals) to screen.

Args: ke : ByRef : KIDD event - all inputs and outputs of a KIDD Kernel call int kidd_write_run_summary(kidd_event_structure* ke, Purpose: Write a text summary of the KIDD run (Warnings, Errors, Fragment Goals) to a file.

Args: ke : ByRef : KIDD event - all inputs and outputs of a KIDD Kernel call path : ByRef : Input complete path to the file to write length : ByVal : Input path string length (omit in Fortran) int kidd_report_flag_description See Section 2.2.1 Subroutine API Functions int kidd_structure_api_version();

Purpose: Returns the KIDD Structure API version that the currently linked KIDD library was compiled against. It is highly recommended to check that the returned value is equal to the kiddc_structure_api_version constant, otherwise, calls to KIDD Structure API functions will likely result in data corruption or a memory fault.

Args: none Returns: int version of the structure interface within the linked KIDD library

For Official Use Only 2-8 int kidd_verify_structure_interface(kidd_event_structure* ke);

Purpose: Used to verify that the structure is properly aligned in memory. It is highly recommended to check this, since structure data misalignment will very likely result in data corruption or a memory fault. To use, first assign a value to the ke.extra.verify_structure_interface structure argument. The returned value should be equal to that value that was assigned to ke.extra.verify_structure_interface as long as the structure has the same data alignment as the currently linked KIDD library expects. If the values are not equal, use the kidd_structure_api_version function to verify that the correct version API is being compiled. If this checks, next verify that the source linking to the KIDD library is not compiled with a data alignment option (-align, -noalign) that conflicts with the KIDD library, which is normally compiled with no align option specified. (Intel Fortran normally aligns structure fields on default natural boundaries)

Args: ke : ByRef : KIDD event - all inputs and outputs of a KIDD Kernel call Returns: int value of ke.extra.verify_structure_interface int kidd_version See Section 2.2.1 Subroutine API Functions float kidd_ran_rcs_gamma See Section 2.2.1 Subroutine API Functions int kidd_thermal_properties See Section 2.2.1 Subroutine API Functions int kidd_initial_propagation See Section 2.2.1 Subroutine API Functions

(FOUO) Structure interface functions that read or write files use unit number 83 to do so. Note that users may wish to set the KIDD event structure argument kidd_event.extra.no_null_term_char_in_strings = 1 to remove the null-terminator char at the end of output strings. This would be desirable if calling from Fortran.

For Official Use Only 2-9

2.1.2 (U) STRUCTURE API IMPLEMENTATION

(FOUO) Before calling any KIDD functions, it is highly recommended to utilize the interface verification functions:

- kidd_version to return the KIDD library version.

- kidd_structure_api_version to return the Structure API version.

- kidd_verify_structure_interface to detect data misalignment.

(FOUO) The kidd_structure_api file contains a kidd_api_verifies boolean function that combines all of the above recommended interface verifications. The function will return true if the KIDD library version matches the API and the KIDD API is working. It will return false on failure and populate a given string with a description of the error.