-
Notifications
You must be signed in to change notification settings - Fork 5
/
README_jeod
445 lines (360 loc) · 19.7 KB
/
README_jeod
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
==============================================================================
Notices:
Copyright © 2023 United States Government as represented by the Administrator
of the National Aeronautics and Space Administration. All Rights Reserved.
Disclaimers:
No Warranty: THE SUBJECT SOFTWARE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY OF
ANY KIND, EITHER EXPRESSED, IMPLIED, OR STATUTORY, INCLUDING, BUT NOT LIMITED
TO, ANY WARRANTY THAT THE SUBJECT SOFTWARE WILL CONFORM TO SPECIFICATIONS, ANY
IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR
FREEDOM FROM INFRINGEMENT, ANY WARRANTY THAT THE SUBJECT SOFTWARE WILL BE ERROR
FREE, OR ANY WARRANTY THAT DOCUMENTATION, IF PROVIDED, WILL CONFORM TO THE
SUBJECT SOFTWARE. THIS AGREEMENT DOES NOT, IN ANY MANNER, CONSTITUTE AN
ENDORSEMENT BY GOVERNMENT AGENCY OR ANY PRIOR RECIPIENT OF ANY RESULTS,
RESULTING DESIGNS, HARDWARE, SOFTWARE PRODUCTS OR ANY OTHER APPLICATIONS
RESULTING FROM USE OF THE SUBJECT SOFTWARE. FURTHER, GOVERNMENT AGENCY
DISCLAIMS ALL WARRANTIES AND LIABILITIES REGARDING THIRD-PARTY SOFTWARE,
IF PRESENT IN THE ORIGINAL SOFTWARE, AND DISTRIBUTES IT "AS IS."
Waiver and Indemnity: RECIPIENT AGREES TO WAIVE ANY AND ALL CLAIMS AGAINST THE
UNITED STATES GOVERNMENT, ITS CONTRACTORS AND SUBCONTRACTORS, AS WELL AS ANY
PRIOR RECIPIENT. IF RECIPIENT'S USE OF THE SUBJECT SOFTWARE RESULTS IN ANY
LIABILITIES, DEMANDS, DAMAGES, EXPENSES OR LOSSES ARISING FROM SUCH USE,
INCLUDING ANY DAMAGES FROM PRODUCTS BASED ON, OR RESULTING FROM, RECIPIENT'S
USE OF THE SUBJECT SOFTWARE, RECIPIENT SHALL INDEMNIFY AND HOLD HARMLESS THE
UNITED STATES GOVERNMENT, ITS CONTRACTORS AND SUBCONTRACTORS, AS WELL AS ANY
PRIOR RECIPIENT, TO THE EXTENT PERMITTED BY LAW. RECIPIENT'S SOLE REMEDY FOR
ANY SUCH MATTER SHALL BE THE IMMEDIATE, UNILATERAL TERMINATION OF THIS
AGREEMENT.
==============================================================================
September 2024
Contents
1. Overview
2. Acknowledgment
3. Usage
4. Key changes since the last release
5. Known issues
6. Regression testing
7. Change history
================================================================================
1. Overview
================================================================================
This section provides overview information about the Johnson Space Center
Engineering Orbital Dynamics (JEOD) software package.
This note describes the most recent release of JEOD, JEOD 5.2. The primary
objectives for 5.2 release of JEOD were to:
* Resolved FIXME and TODO items in the code (see section 4 for detail)
* Implemented GoogleTest stub and mock classes for unit tests
* Modernization of code using clang-tidy
* Improved code formatting using auto formatting tool.
* Added test cases for alt_pfix and alt_inertial
* API improvements
* Fixed bugs
The key features of this release are highlighted in section 4 below.
The JEOD 5.2 Release
****************************
The release comprises
* Models. The JEOD models provide the functionality needed to represent
vehicles that translate and rotate in a space environment. The models are
organized into four main groups: dynamics, environment, interactions, and
utilities. Each of these four groups corresponds to a subdirectory of the
JEOD models directory. The immediate subdirectory of each model group
directory contains exactly one JEOD model. Models are accompanied with
test artifacts to verify that a model satisfies its requirements. For JEOD
5.2, there is also an experimental directory containing experimental
models that are not yet rigorously verified and documented up to typical JEOD
standards. Users planning to these experimental models should understand the
risk associated with them and there are currently no plan for documentation
and verification of these models.
* Test and Analysis Tools. Trick simulations have long been used to test the
JEOD models. JEOD 5.2 contains Trick-compatible versions of all
previously existing simulations.
* Training Materials. Getting a picture of how JEOD works by reading the
overview and model documentation can be tough. The JEOD training materials
are located in the $JEOD_HOME/docs/Training directory. These materials
systematically show users how to use JEOD via the course lecture notes,
lessons covering every extant JEOD model (except the SPICE interface model
and experimental models) and tutorial exercises of increasing complexity.
* Verification and Validation Simulations. In addition to the model-level
verification testing, JEOD 5.2 has been tested against best estimate of
trajectory (BET) data from various orbiting vehicles. These documented
integrated tests not only demonstrate that JEOD properly models the space
environment, they also serve as additional examples of how to use JEOD in a
realistic simulation. Since JEOD 5.0, some BET data were removed from the
release so that JEOD can be host on Github.com. However, validation result
are still presented in the top-level JEOD documentation.
* Top-level Documentation. JEOD is well documented from the top-level down.
The top-level JEOD documentation is the file $JEOD_HOME/docs/JEOD.pdf.
The dynamic comparison simulation is described in the file
$JEOD_HOME/verif/SIM_dyncomp/docs/DYNCOMP.pdf.
* Model Documentation. Each model has a model document located in the file
$JEOD_HOME/models/<model_group>/<model_name>/docs/<model_name>.pdf.
* HTML Pages. The Application Programmer Interface (API) to the JEOD models can
be viewed by directing a browser to file://$JEOD_HOME/html/jeod/index.html.
These HTML pages are automatically generated from the JEOD source code by
doxygen. In addition to displaying the API, the JEOD PDF documentation files
are accessible through these HTML pages.
================================================================================
2. Acknowledgment
================================================================================
JEOD v5.2 release accepted the following pull requests submitted by GitHub users:
* Title: Change Logging Python Utility to Log "parent/this" Varaibles
- GitHub User: miwr0
- URL: https://github.com/nasa/jeod/pull/10
================================================================================
3. Usage
================================================================================
Important Note
*******************************************
According to https://endoflife.date/centos, Centos 7's support cycle is ended
on 2024-06-30. The ended of life impacted the ability to perform CI on CentOS 7.
Therefore, CentOS 7 is no longer actively supported starting JEOD 5.2
Instructions for use in a Trick environment
*******************************************
The JEOD package is first and foremost a package designed for use in simulations
developed with the Trick simulation environment. This release of JEOD 5.2
was tested with Trick 19.7.2, using compiler gcc 4.8.5 on CentOS 7.6, 7.5.0 on
Ubuntu 18.04, 8.5.0 on Oracle Linux 8, and LLVM version 18.1.8 on Mac.
Required environment variables
------------------------------
The following environment variables must be set to use JEOD in conjunction
with the Trick simulation environment.
JEOD_HOME The JEOD_HOME environment variable must point to the
top-level JEOD directory (i.e., the directory that
contains this README_jeod file).
TRICK_CFLAGS The TRICK_CFLAGS & TRICK_CXXFLAGS environment variables
TRICK_CXXFLAGS must add the JEOD models directory to the include path
list. The variable must contain "-I${JEOD_HOME}/models".
TRICK_HOME The adjacent list of three additional Trick environment
TRICK_VER variables is just a partial list of those required by
TRICK_HOST_CPU Trick. Please refer to Trick documentation for details.
It is recommended that the system administrator provide standard shell
scripts that properly set the above environment variables.
Simulation specification and compilation
----------------------------------------
Trick simulations are specified in an S_define file and built using the Trick-
provided trick-CP utility. Please refer to the Trick user manual for a
description of an S_define file and the use of trick-CP.
ER7_Utils
---------
There is no need to separately obtain the ER7_Utils package when JEOD is used
within a Trick environment. ER7_Utils is distributed with Trick as a
third-party package. The trick-CP utility makes the package visible to the
compiler via an include path that begins with "er7_utils/integration".
Required Package
---------
JEOD 5.2 requires installation of swig3 and cmake3
================================================================================
4. Key changes since the last production release (JEOD 5.2)
================================================================================
Resolved FIXME and TODO items in the code
-------------------------
Resolved total of 34 FIXME/TODO items in the code. These include:
- Improved failure messages in DynManager::initialize_model and
JEODTrick10MemoryInterface::get_name_at_address
- Changed JeodDynBodyIntegrationLoop::add_integrable_object to allow DynBody
objects without failure
- Added JeodSimulationInterface::Mode to MessageHandler
- Added check for duplicates in DynBodyContraintsSolver::add_attached_constraints
- Added an inheritance diagram to DynBodyInit documentation
Implemented GoogleTest stub and mock classes
-------------------------
Started the implementation of stub and mock classes of some of the models to
work with GoogleTest. These stub and mock classes can also be use for unit
testing of models developed based on the JEOD classes. Stub and mock classes for
the following models are implemented for JEOD v5.2 release. Additional stub and
mock will be implemented in future releases.
* Added partial or complete mock classes for:
- class MassBody
- class BodyRefFrame
- class DynBody
- class BodyAction
- class DynManager
- class DynamicsIntegrationGroup
- class RefFrame
- class JeodIntegrationGroup
- class JeodIntegrationTime
- class er7_utils::IntegrableObject
- class er7_utils::IntegrationControls
- class er7_utils::IntegratorConstructor
- class MessageHandler
- class JeodIntegratorInterface
- class JeodMemoryInterface
- class JeodSimulationInterface
- class GravityControls
- class EphemerisRefFrame
- class SinglePointEphemeris
* Added ER7 Utils stubs required to compile jeod unit tests:
- class BaseIntegrationGroup
- static method Er7UtilsDeletable::delete_instance_internal
- class IntegrationControls
- static method IntegratorConstructorFactory::create
- class IntegratorConstructor
- class IntegratorResultMergerContainer
- class LeftQuaternionGeneralizedPositionDerivativeFunctions
Modernization of code using clang-tidy and improved code formatting using ClangFormat
-------------------------
Used clang-tidy to modernize code from older C concepts to more modern C++11
concepts. The main families of options used included bugprone, cppcoreguidelines,
llvm, modernize, performance, and readability.
Improved code formatting using ClangFormat to provide consistent code format.
Implemented formatting check in development CI to enforce formatting standards
in the code
API Improvements
-------------------------
* Improvement in JEOD_MAKE_SIM_INTERFACE
- Updated to the JEOD_MAKE_SIM_INTERFACE macro that enable the function to be
used for models that are based on JEOD classes but outside the "jeod" namespace.
* MassBodyInit::allocate_points replaces setting MassBodyInit::num_points and
MassBodyInit::points using trick.TMM_declare_var_s in input files. Items in
MassBodyInit::points are now accessed with MassBodyInit::get_mass_point
* All char * have now been converted to std::string
* MET_atmosphere constructor now takes in a reference to time_utc.trunc_julian_time
and the MET_atmosphere::update_time method has been eliminated.
* Complete conversion from Python 2 to Python 3.
Critical Bug Fixes
-------------------------
- TreeLinks::child_head() and TreeLinks::child_tail() were previously commented
saying that they returned iterators, when they actually return references.
This caused a bug that has now been resolved in JEOD v5.1.1 and documented in
this release.
================================================================================
5. Known issues
================================================================================
The issues known to exist with the JEOD 5.2 release are:
* Non-Trick demonstration.
The demonstration of the usability of JEOD outside the Trick environment is
not currently maintained and may not work with this release.
* Trick support.
JEOD 5.2 is officially tested with Trick 19.7.2 or newer. Backward
compatibility with older versions of Trick are not guarantee, but most models
should still work with Trick 19.0 or newer. Users are strongly encouraged to
upgrade to a newer version of Trick if their project allows.
* Trickified build works for all the regression test sims on CentOS 7,
Ubuntu 18, Oracle Linux 8, and MacOS with Apple silicon.
- However, Observed on Mac but could be a cmake version issue (cmake v3.30.3)
building sims in parallel using TRICKIFIED=1 may cause problems due to cmake
updating a file despite nothing to update. This does not rebuild any objects
or libraries but can trigger a re-install of the libraries. A sim starting
to link in the libjeod.a will end up working with the partially written
library file and fail to build.
- The workaround that retains parallel sim build is to set the
$JEOD_HOME/trickified (ie. chmod -w trickified) directory to read-only after
the building the jeod library and trickified builds. The make rules will
recognize the read-only state and only link in the libraries without
attempting to rebuild.
* Experimental models.
For this release, there is a directory named $JEOD_HOME/models/experimental.
It contains new models that have NOT been rigorously verified or
documented up to typical JEOD standards. Users planning to utilize these
experimental models should understand the risks associated with them and
that there are currently NO plans for documentation and verification of
these models.
================================================================================
6. Regression testing
================================================================================
Several regression tests are provided with this release. These regression tests
are used internally to verify that the release behaves as expected. These tests
are not necessarily the same tests used for validation. External users can use
these tests to verify that their installation of JEOD yields results comparable
to those supplied with the release. The regression tests are located in
* $JEOD_HOME/verif
This directory contains the simulations used to verify that JEOD operates
correctly as a whole.
* $JEOD_HOME/sims
This directory contains an abbreviated Apollo simulation.
* The verif subdirectories found in the JEOD model directories. Some of these
contain simulations supplied with regression test data. Most models contain
verification simulations or unit tests.
Note: A small number of these model verification tests fail by design.
All simulation runs that intentionally fail have fail or FAIL embedded
in the simulation RUN directory name.
Caveats:
* All regression test data supplied with the release were generated using a
64-bit machine running CentOS 7.5 and compiled with gcc 4.8.5 and Oracle
Linux 8 with gcc 8.5.0. Users should not expect exact numeric matches when
using a different machine architecture, a different operating system, or a
different compiler.
An extreme example of this is the RUN_euler case of the
utils/integration/verif/SIM_integ sim. The stability of the Euler method
is such that the results of this case are "confusion-limited"; that is, the
results for this case exhibit chaotic system-dependent behavior. Note that
use of the Euler integration method is generally not recommended.
* Regression test scripts are provided in JEOD v5.2. These scripts are used
internally to verify the release behaves as expected. Users planning to use
these scripts for their own regression test are free to modify the script
to fit their needs. However, no support will be provided for these regression
test scripts.
================================================================================
7. Change history
================================================================================
****************************
JEOD 5.2, September 2024
****************************
* Changes to models.
- Total of 34 FIXME/TODO items in the code were resolved in this release. These
include changes in:
# Improved failure messages in DynManager::initialize_model and
JEODTrick10MemoryInterface::get_name_at_address
# Changed JeodDynBodyIntegrationLoop::add_integrable_object to allow DynBody
objects without failure
# Added JeodSimulationInterface::Mode to MessageHandler
# Added check for duplicates in DynBodyContraintsSolver::add_attached_constraints
# Added an inheritance diagram to DynBodyInit documentation
- Fixed bug in TreeLinks. The issue was resolved in JEOD v5.1.1 release.
Documenting in JEOD v5.2 release note.
* Changes to sims and unit tests.
- Added test cases for alt_pfix and alt_inertial frames
- Implemented stub and mock classes that work with GoogleTest for unit test
* Changes to Documentation
- Fixed metrics table in some model documentations
- JEOD documentations were updated for the JEOD 5.2 release.
* Changes to tools.
- Modernization of code using clang-tidy
- Formatting of the code using ClangFormat to provide consistent formatting
- Implemented formatting check in CI to enforce formatting standard
****************************
JEOD 5.1, July 2023
****************************
* Changes to models.
- Added support for Moon Mean Earth (Moon_ME) body fixed frame.
- Added kinematic attachment capability.
- Improved ease of use for calculating derivative states for a child body.
- Improved checkpoint-restart for standard STL containers.
- Improved ephemeris data generation using mako template.
* Changes to sims and unit tests.
- Fixed SIM_spice.
- Completed SIM_dyncomp_structure.
- Added test cases to verify kinematic attachment.
- Improved checkpoint-restart verification sim to test dynamically allocated
objects.
- Fixed training solution sims.
* Changes to Documentation
- JEOD documentations were updated for the JEOD 5.1 release.
* Changes to tools.
- Implemented static analysis job (CppCheck and Flawfinder) in CI.
****************************
JEOD 5.0, August 2022
****************************
* Changes to models.
- removed some best estimated data (BED) from actual space mission from the
software.
- removed TCAM model and Atmosphere Interface models.
- Updated checkpoint tag for standard STL containers.
- Updated unit specification for angle.
- Included new set of gravitational coefficients for Moon from GRAIL.
* Changes to sims and unit tests.
- Removed SIM_Grace
- Removed RUN_champ, RUN_envisat, RUN_iss, RUN_lageos, and RUN_tdrs from
SIM_Earth_Moon
- Training solution sims were updated to JEOD v5.0
* Changes to Documentation
- Training documentations were to JEOD v5.0
- Top-level JEOD documentation and some model documentations were updated
such that they only contains information that are publicly releasable.
- JEOD documentations were updated for the 5.0 release
- Removed programmer information from the source code to prepare for open
source
* Changes to tools.
- Using CppCheck and Flawfinder for static analysis
- Using Lcov for code coverage.
- Implemented a manual code coverage job in CI