Catégorie:User Manual 4.11

Introduction

This document is the main user manual of the PATRIUS library, which provides Java classes in a wide range of themes related with space flight dynamics.

The library has several purposes :

• to be a basis for the next generation FDS development
• to be used in mission analysis and internal studies

Its classes contain the main basis algorithms and objects representation that shall be used in further developments.

For each theme, a specific manual is available.

Applicable and Reference Documents

Applicable Documents

[A1] CDCF- Fonctions de Base du Patrimoine de Dynamique du Vol, V1.2, SIRIUS-CF-DV-0049-CN, 2011.
[A2] Dossier de réutilisation Orekit et Commons Math, V1.0, SIRIUS-DLR-DV-0080-CN, 2010.

Glossary

Conventions

All the user manuals contain some java code sample as use examples.

These samples are recognizable by the following colors convention :

Vector3D originCone = new Vector3D(1.0, 1.0, 1.0);
Vector3D direction = new Vector3D(2.0, 0.0, 0.0);
double angle = FastMath.PI / 4.0;
double height = 5.0;
RightCircularCone cone = new RightCircularCone(originCone, axis, angle, height);

PATRIUS uses the International System of Units (SI units) (m, kg, s, N, etc.). It is used for all PATRIUS input/output as well as internally for any computation.

Overview

This document is an aid for developers coding software using the PATRIUS library. The library provides Java classes to represent basis objects and contains low level algorithms to be used in the new FDS and mission analysis softwares. The user guide describes and explains the use of every class and functionality available.

Each theme of the library is the object of a specific document. These themes are :

• Math basis
• Flight dynamics basis
• Attitude
• Spacecraft
• Orbits
• Mission
• Tools
• Support

PATRIUS is under Apache Licence 2.0.

Quick Start

Here is a description of each theme of the PATRIUS library and an overview of its contents. See each associated document for the details.

Mathematics

This theme is not directly linked to flight dynamics. It include. It provides the mathematical tools for the rest of the library.

Its contains classes for :

• function analysis (interpolations, polynomials, ...)
• numerical intergrators
• geometry (planes, lines, shapes, rotations, 3d vectors and matrixes...)
• low level functions and constants (sine, cosine, PI, ...)
• linear algebra (real matrix and vectors, decompositions and other matrix computations, ...

The Mathematics User Manual can be found here.

Flight Dynamics

This theme contains the basis of orbital mechanics :

• position-velocity and orbital parameters conversions
• frames and frames transforms
• dates and time scales
• time intervals

The Flight Dynamics User Manual can be found here.

Spacecraft

This theme contains everything useful to describe a spacecraft and its use :

• general architecture (describing the spacecraft by one or several parts)
• geometry
• mass caracteristics
• equipments (GS, antenna, instruments and associated computations...)
• caracteristics used in forces computations (radiative, drag...)
• torques computations

The Spacecraft User Manual can be found here.

Attitude

This theme contains the tools to predict the spacecraft attitude:

• attitude laws
• cinematics and guidance

The Attitude User Manual can be found here.

Orbits

This theme contains everything useful to propagate an orbit in time and perform orbits restitutions :

• numerical and analytical propagators
• physical models (for forces)
• Measures and filtering tools

The Orbits User Manual can be found here.

Mission

This theme regroups the events computation, projections and use tools.

The Mission User Manual can be found here.

Tools

This theme comprises some external tools such as the ephemeris comparator.

The Tools User Manual can be found here.

Support

This theme is cross-functional. It contains for example the explaination of the data manager use and action.

The Support User Manual can be found here.

Thread-Safety

For all content belonging to the PATRIUS library, the thread safety of every class will be evaluated, and the results listed here.

The known levels of thread safety for a class are:

• immutable: the contents of an instance never change after creation, therefore the class is thread-safe.
• unconditionally thread-safe / thread-safe: the whole class is thread-safe by design.
• conditionally thread-safe: the class is thread-safe if certain conditions (specific to the class) are met.
• not thread-safe: the class is not thread-safe. If the class is used in a threaded environment, all accesses

to the class must be synchronized.

• thread-hostile: the class is known to break threads, even when no instance is shared between threads!

About the comments

Some recurring comments are explained here :

• "Exposed mutable attributes.": the class contains attributes that either "come" from outside the class, or whose reference can be obtained from the class. Unless the attributes are thread-safe or accessed in a thread-safe manner somehow, this breaks the thread safety of the class.
• "documented as immutable, but technically untrue": Patrius document classes that are non-final as immutable- but the (quite strict) usual definition of immutability mandates that an immutable class must be final, because a non-final class can be subclassed and this subclass can break immutability "silently" (an user could access this subclass through the superclass reference and believe it is immutable due to the superclasses' documentation.) Therefore: when a class is documented as immutable, it means only the documented implementation is immutable. For safety, we chose to document these classes here as "unconditionally thread-safe", a statement that is not assumed to be preserved by subclassing.

Thread safety

Patrius-tools thread safety

Here is a list of all patrius-tools classes and thread-safety:

• when these are documented as "immutable" in their javadoc, it is stated so.
• the remainder was evaluated by the PATRIUS team.

The list of all validated classes is also available in the SVS.

NOTE : thread hostility has not been systematically researched, so it is not fully documented in this revision.

Note : Frames and thread-safety

It was determined that several Frame implementations were thread-hostile.

The current evaluation of these changes from a thread-safety point of view leads us to state the following :

• The IERS frames (GCRF, CIRF, TIRF and ITRF) are thread-safe.

Known Issues

None.