Basilisk Release Notes
This software is currently in a limited alpha public-release. The Basilisk development is still in progress, and some behaviors and setups API's are bound to change. That said, we are very excited by the great capabilities that this software already has, and plan to be updating this software regularly. There is some documentation in terms of Doxygen generated HTML documentation, but also documentation within the code, and several Basilisk modules that are math heavy have LaTeX'd documentation folders as well. Best place to start is to run the integrated tutorial scripts inside the SimScenarios folder. More documentation and tutorial scripts are in development.
In Progress Features:
- ability to integrate custom Basilisk modules that are kept outside of the core Basilisk folder
- more integrated BSK scenarios and tutorials
- GPU based methods to evaluate solar radiation pressure forces and torques
- atmospheric drag evaluation using multi-faceted spacecraft model
- New Unity-based Basilisk visualization tool
- Python 3 support
- live plotting capability during a BSK run
Version 0.5.0 (April 10, 2019)
`attTrackingError` has updated documentation and unit tests.
navAggregate module has new documentation and unit tests.
small FSW algorithm enhancements to ensure we never divide by zero
new unit test for RW-config data
- included a new environment abstract class that creates a common interface to space environment modules like atmospheric density, or magnetic fields in the future. This currently implements the exponential model, but will include other models in the future. NOTE: this change breaks earlier simulation that used atmospheric drag. The old `exponentialAtmosphere` model usage must be updated. See the integrated and unit tests for details, as well as the module documentation.
added new documentation on using the new atmosphere module to simulate the atmospheric density and temperature information for a series of spacecraft locations about a planet.
- updated documentation and unit tests of `celestialTwoBodyPoint`
- added a new planetary magnetic field module. Currently it provides centered dipole models for Mercury, Earth, Jupiter, Saturn, Uranus and Neptune. This will be expanded to provide convenient access to other magnetic field models in the future.
updated `eulerRotation()` to remove optional output message and did general code clean-up
updated `mrpRotation()`, new PDF documentation, did code cleanup, updated unit tests, removed optional module output that is not needed
- updated `MRP_Feedback()`, new PDF documentation, did code cleanup, updated unit tests to cover all code branches.
Added a new tutorial on using the magnetic field model.
Updated `mrpMotorTorque()` with code cleanup, updated doxygen comments, PDF documentation and comprehensive unit test.
- Added documentation to `thrFiringRemainder` module
- Added documentation to `thrFiringSchmitt` module
- Updated documentation of `thrMomentumManagement` module
- Updated documentation of `thrMomentumDumping` module
- Added documentation of `MRP_PD` module
- added a new tutorial on how to use the planetary magnetic field model.
Version 0.4.1 (February 20, 2019)
updated Documentation on `rwNullSpace` FSW module
updated how the FSW and Simulation modules are displayed with the DOxygen HTML documenation, as well as how the messages are shown. Now the use can click on the "Modules" tab in the web page to find a cleaner listing of all BSK modules, messages, utilities and architecture documentation.
modified the `cmake` file to allow the build type to be passed in from the command line
updated Doxygen documentation on `cssWlsEst()`
updated documentation and unit tests of `cssComm()` module
Version 0.4.0 (February 11, 2019)
Integrated the `conan` package management system. This requires conan to be installed and configured. See the updated Basilisk installation instructions. It is simple to add this to a current install. Further, the CMake GUI application can't be used directly with this implementation if the app is double-clicked. Either the GUI is launched form a terminal (see macOS installation instructions), or `cmake` is run from the command line (again see your platform specific installation instructions). Using `conan` now enables BSK to be compiled with specific support packages, and will allow us to integrate other packages like OpenCV, Protobuffers, etc. into the near future in a flexible manner.
updated install instructions to allow for pytest version 4.0.0 or newer
- updated code to remove some depreciated python function call warnings
Added a new sun heading module computed exclusively from ephemeris data and spacecraft attitude (sunlineEphem). Documentation and a unit test are included.
Added a new scenario that shows how to simulate multiple spacecraft in one simulation instance.
Added a spacecraftPointing module that allows a deputy spacecraft to point at a chief spacecraft. Besides that, added a scenario that demonstrates the use of this new module.
added the ability to the thrForceMapping FSW module to handle thruster saturation better by scaling the resulting force solution set.
Added lots of new unit tests to BSK modules
rwNullSpace() module now sets ups module states in reset() instead of crossInit(), and includes new documentation and unit tests
Version 0.3.3 (November 18, 2018)
Added a new message output with the CSS fit residuals. This is optional. If the output message is not set, then this information is not computed.
Updated `sunSafePoint()` to allow for a nominal spin rate to be commanded about the sun heading vector. The unit tests and module documentation is updated accordingly.
Added a new scenario `scenarioAttitudeFeedbackNoEarth.py` which illustrates how to do an attitude only simulation without any gravity bodies present.
Updated the macOS Basilisk installation instructions to make them easier to follow, and illustrate how to use the macOS provided Python along with all the Python packages installed in the user Library directory. This provides for a cleaner and easier to maintain Basilisk installation.
Created new switched CSS sun heading estimation algorithms called `Sunline_SuKF` and `Sunline_SEKF`. These switch between two body frames to avoid singularities, but with direct body rate estimation. Previous filters `Sunline_UKF`, `Sunline_EKF`, and `OKeefe_EKF` either subtract unobservability or difference sunheading estimate for a rate approximation.
Updated the Windows specific install instructions to include explicit steps for setting up and installing Basilisk on machine with a fresh copy of Windows 10.
- Added policy statements to the CMake files. This now silences the warnings that were showing up in CMake 3.12 and 3.13
- Modified CMake to silence the excessive warnings in XCode that `register` class is no depreciated in C++
Version 0.3.2 (August 14, 2018)
Fixed an issue with the eclipse unit test.
updated the installation instructions to warn about an incompatibility between the latest version of `pytest` (version 3.7.1). Users should use a version of `pytest` that is 3.6.1 or older for now until this issue is resolved.
Updated the `.gitignore` file to exclude the `.pytest_cache` folder that pytest generates with the newer versions of this program
Version 0.3.1 (August 1, 2018)
Tutorials added for BSK_Sim architecture. Added the ability to customize the frequency for FSW and/or dynamics modules.
Updated the dynamics thruster factor classes. This streamlines how thrusters can be added to the dynamics. Also, a new blank thruster object is included in this factory class to allow the user to specify all the desired values.
bskSim now adds 8 thrusters to the spacecraft. These are not used yet, but will be in future bskSim scenarios.
Modified how bskSim now includes CSS sensors in the spacecraft dynamics setup
Modified the FSW `sunSafePoint()` guidance module to read in the body angular velocity information from standard `NavAttIntMsg`. This will break any earlier simulation that uses `sunSafePoint()`.
- FIX: update the `sunSafePoint()` input connection to use the current message format.
- Fixed an issue with energy not conserving if the fully coupled VSCMG imbalance model is used. This imbalanced gimbal and wheel version now conserves momentum and energy!
- Added initial draft of VSCMG module documentation
- Added documentation to all the bskSim scenarios inside `src/test/bskSimScenarios`. The documentation now outlines how the bskSim class can get setup and used to create complex spacecraft behaviors with little code.
Version 0.3.0 (July 23, 2018)
Updated cssWlsEst() module to also compute a partial angular velocity vector.
New FSW Guidance module `mrpRotation()` to perform a constant body rate rotation. The initial attitude is specified through a MRP set.
Enhanced Linux installation instructions
Updated the simIncludeThruster to use the same factor class as the RW factory class. This will break old scripts that use the old method of setting up Thrusters with this helper function.
- FIX: Update the script to use the new factory class. Examples are seen in `src/simulation/dynamics/Thrusters/_UnitTest/test_thruster_integrated.py`.
Updated bskSim to use the RW factory class to setup the simulation RW devices, as well as to use fsw helper functions to setup the RW FSW config messages
At supportData/EphermerisData, updated the leap second kernel version to from 0011 to 0012.
Added a force and torque calculation method in the stateEffector abstract class, and provided the necessary method calls in spacecraftPlus. This allows for stateEffectors to calculate the force and torque that they are imparting on the rigid body hub. The hingedRigidBodyStateEffector and the linearSpringMassDamper classes provide their implementation of these calculations.
Fixed an issue with `extForceTorque` effector where the flag about having a good input message was not being initialized properly. This caused a rare failure in the unit test.
Reaction wheel state effector has an updated friction model that allows the user to implement coulomb, viscous, and static friction.
Reaction wheel state effector now has max torque saturation logic in which the wheels can only implement a maximum wheel torque and max wheel speed saturation logic in which if the wheel speed goes over the maximum wheel speed, then the wheel torque is set to zero.
A new method called writeOutputStateMessages was added to the stateEffector abstract class which allows for stateEffectors to write their states as messages in the system and the states will always be written out to the system after integration. This fixed an issue with reaction wheels where the commanded torque information needs to be tasked before the spacecraft but the reaction wheel state messages need to be written out after integration.
A new dynamics class called `spacecraftDynamics` has been created. This allow multiple complex spacecraft systems to be either rigidly connected or free-flying. This allow for example a mother craft to house a daughter craft which has its own RWs, etc, and then release the daughter craft at a specified time.
Cleaned up the gravity effector class variable names, and streamlined the evaluation logic. The gravity effector documentation has been updated to include information on the the multi-body gravity acceleration is evaluated.
Updated the FSW modules `MRP_Feedback`,`MRP_Steering`, `dvAccumulation` and `oeStateEphem` to zero out the output message first in the `Update()` routine.
Fixed an issue with the RW factory class and the Stribeck friction model not being turned off by default.
added a new bskSim based tutorial scenario that illustrates a sun-pointing control while the spacecraft goes through a planets shadow.
Version 0.2.3 (June 12, 2018)
- Improved how the `fuelSloshSpringMassDamper` effector class works. It is now renamed to `LinearSpringMassDamper`. It can be used to simulate both fuel sloshing, but also structural modes. If the `LinearSpringMassDamper` is connected to a fuel tank, then it's mass depends on the amount of fuel left. The associated unit test illustrated how to setup this last capability. The module also contains documentation on the associated math.
- A new `SphericalPendulum` effector class has been added. For rotations a spherical pendulum is a better approximation rotational fuel slosh. This effector can model rotational fuel slosh if connected to a tank (see unit test again), or it can model a torsional structural mode if not connected to a tank. Associated math documentation is included with the class.
- The booleans useTranslation and useRotation have been removed from the `HubEffector()` class. The defaults in hubEffector for mass properties: `mHub = 1`, `IHubPntBc_B = diag`(1), and `r_BcB_B = zeros(3)`, enable us to evaluate the same code no matter if the desire is only to have translational states, only rotational states, or both. This allows for less logic in hubEffector and removes possibility of fringe cases that result in unexpected results from a developer standpoint. The fix for if your python script is not working related to this change:
- FIX: Remove any instances of useTranslation or useRotation defined in the hubEffector class.
- Changed name of the method `computeBodyForceTorque` to `computeForceTorque` in the `dynamicEffector` abstract class and any inheriting classes. This avoids the confusion of thinking that only body frame relative forces can be defined, but in reality this class gives the ability to define both external forces defined in the body frame and the inertial frame.
Fixed an issue in `RadiationPressure` where the cannonball model was not computed in the proper frame. An integrated test has been added, and the unit test is updated. Note that the `RadiationPressure` model specification has changes slightly. The default model is still the cannonball model. To specify another model, the python methods `setUseCannonballModel()` or `setUseFacetedCPUModel()` are used. Note that these take no argument anymore.
- FIX: remove the argument from `setUseCannonballModel(true)` and use the methods `setUseCannonballModel()` or `setUseFacetedCPUModel()` without any arguments instead.
Version 0.2.2 (May 14, 2018)
- Fixed a build issues on the Windows platform is Visual Studio 2017 or later is used.
- Unified the Coarse Sun Sensor (CSS) sun heading filtering modules to use the same I/O messages. All used messages are now in the fswMessage folder.
- Made the CSS sun heading filter messages consistently use the CBias value. This allows particular sensors to have an indiviual (known) scaling coorection factor. For example, if the return of one sensor is 10% stronger then that of the other sensors, then CBias is set to 1.10. Default value is 1.0 assuming all CSS units have the same gain.
- The `src\tests\bskSimScenarios` folder now functions properly with the `bskSim` spacecraft class.
- The tutorial scripts in `src\tests\scenarios` are now simplified to pull out the unit testing functionality. The unit testing is now down with the `test_XXX.py` scripts inside the `src\tests\testScripts` folder.
- The `bskSim` tutorial files are now tested through pytest as well. The file `testScripts\bskTestScript.py` calls all the `bskSim` tutorial fails and ensures they run without error.
- Added messages for current fuel tank mass, fuel tank mDot, and thruster force and torque
- Changed the linearAlgebra.c/h support library to avoid using any dynamic memory allocation.
- Added some new function to linearAlgebra.c/h while making the library use the new BSK_PRINT() function.
- Added ability to simulate noise to the RW devices.
- Created a more complete spacecraft python simulation class called BSKsim, and recreated some BSK tutorial scripts to use BSKsim instead of the more manual spacecraft setup in the earlier scripts.
- Developed general functions to add saturation, discretization and Gauss Markov processes to signals.
- Created a new BSK_PRINT() function. Here the coder can tag a message as an ERROR, WARNING, DEBUG or INFORMATION status. The printout can be set to selectively show these print statements.
- First open beta release of Basilisk
- Moved to a new file architecture. This means older BSK python scripts need to be updated as the method to import BSK has changed.
- The source an now be forked from Bitbucket
- Percompiled binaries are provided through a python pip install wheel file.
- The Doxygen documentation now pulls in the BSK module description PDF file and makes it available via the class defintion html page.
- The tutorial python scripts are now moved to `src/test/scenarios`
- The `pytest` comman should now be run within the `src` sub-directory
- Updated fuel slosh model documentation
- Updated fuel tank documentation
- Adding noise and corruptions using a new utility to the BSK modules (in progress)
- New N-panel hinged rigid body module
- New 2-panel hinged rigid body module
- Added CSS sun-heading estimation tutorial script
- Added O'Keefe CSS sun-heading estimation module
- New Monte-Carlo capability that uses multiple cores and hyperthreading to accelerate the MC evaluations. Data is retained and stored for each MC run for robustness. See `test_scenarioMonteCarloAttRW.py` for an example.
- Coarse Sun Sensor (CSS) modules can now scale the sensor output with the distance from the sun.
- CSS now have updated documentation that includes validation results.
- CSS, IMU have updated means to apply sensor corruptions.
- IMU, simple_nav and star tracker modules have been updated to use now internally Eigen vectors rather than C-Arrays. NOTE: if you have simulation scripts that use these modules you may have to update the script to set sensor states as Eigen vectors from python.
- All the dynamics, thruster and sensor simulation modules have expanded documentation and valdiation unit and integrated tests. The validation results are automatically included in the module TeX documentation.
- new unit tests to validate the multi-body gravity simulation code in `SimCode/dynamics/gravityEffector/_UnitTest/test_gavityDynEffector.py`
- new hinged rigid body tutorial script in `SimScenarios/test_scenarioAttGuideHyperbolic.py`
- new tutorial to do velicity frame pointing on a hyperbolic orbit in `SimScenarios/test_scenarioHingedRigidBody.py`
- fixed various unit test issues that came up on the non-macOS builds
- added reaction wheel effector documentation
- added `orb_elem_convert` documentation
- added `boreAngCalc` documentation
Lots of new module documentation which includes a discussion of what is being modeled, the validation tests, as well as a user guide to the module. The new documentation includes:
- Thruster DynEffector module
- ephemeris conversion module
- Coarse Sun Sensor module
- Updated BSK module template documentation
- Updated documentation for IMU Sensor module
- Gravity Effector module
- SimpleNav Sensor module
- Hinged Panel StateEffector module
- New tutorial scripts on
- using CSS modules
- using fuel tank module and the fuel slosh particle StateEffector
- How to use MRP_Steering() along with the rate tracking sub-servo module
- The CSS modules now use the planetary shadow message information to simulated being in a planet's shadow
- SRP DynEffector modules now simulates the impact of being in a planets shadow
- Included a method to validate all the AVS C-Function libraries like rigidBodyKinematics, linearAlgebra and orbitalMotion when the Basilisk pytest command is called. There is also some documentation on using these libraries in /SimCode/utilitiesSelfCheck/_Documentation
- Updated the RW and gravitational body (i.e. adding Earth, sun, etc. to the simulation) to use new factory classes. If you did use the older simIncludeRW.py or simIncludeGravity.py libraries, you'll need to update your python code to work with the new factory classes.
- A planetary eclipse model has been added. This allows for the shadow of one or multiple planets to be taken into account, including the penumbra region. This module writes an output message indicating if the spacecraft is in full sun light, partial shadow, or full shadow of the sun.
- The body-fixed spacecraft structure frame has now been removed from the simulation and flight algorithm codes. All spacecraft vectors and tensors are now set directly in the body frame B. If the spacecraft parameters are given in terms of an alternate structure frame, these vectors and tensor must be transformed into the body frame first before being set in BSK.
- The integrated tutorial test for using a Python based BSK module now has some documentation.
- Created a method to compute the orbital potential and angular momentum energy. This allows for the kinetic energy and angular momentum checks to flat-line even if the satellite is in orbit. The spherical harmonics of the planet are taken into account as well.
- Included a new Extended Kalman Filter module that determines the body-relative sun heading using the CSS signals.
- There is a new capability to now write BSK modules in Python, and integrated them directly with the C and C++ BSK modules. Documentation is still in progress, but a sample is found in
- A new Variable Speed Control Moment Gyroscope (VSCMG) state effector module has been created. This module provides a torque-level VSCMG simulation which also includes the gyro frame or wheel being imbalanced. If the latter modes are engaged, the simulation does slow down noticeably, but you get the full physics.
- In the simulation the initial spacecraft position and velocity states are now specified now using the spacecraft center of mass location C, not the body fixed point B. This greatly simplifies the simulation setup. Upon initialization, the sim determines what the true center of mass of the spacecraft is using all time varying mass components, and sets the proper B point position and velocity vectors.
- Specifying the initial spacecraft position and velocity states can now be done anywhere before the BSK initialization. The user sets init versions of the position and velocity vectors. The setState() method on the state engine thus doesn't have to be used.
- There is a new
initializeSimulationAndDiscover method to init the BSK simulation that automatically checks if messages are shared across multiple simulation threads. See the modified
SimScenarios/test_scenarioAttitudeFeedback2T.py file for how this simplifies the dual-threaded setup.
PRV_Steering FSW modules have been broken up into a separate kinematic steering command (commanded desired angular velcocity vector) and an associated angular velocity servo module name
rateServoFullNonlinear. This will break any existing code that used either of these two attitude steering modules. The Python simulation code must be updated to to account for these new modules as done in the MRP_Steering integrated test
- All unit and integrated tests now pass on Linux. The root issue was a varaible length string variable in an output message. These strings have now been removed as they are no longer needed.
- The position and velocity of the center of mass of the spacecraft was added to the messaging system, so now the spacecraft’s translational states can be logged by the center of mass of the spacecraft (r_CN_N and v_CN_N) or the origin of the body frame which is fixed to the hub (r_BN_N and v_BN_N). Additionally, the mass properties of the spacecraft was organized into an updateSCMassProps method that incapsulates the calculations of mass property calculations.
- Updated UKF FSW module to be able to run on gryo only information when the star tracker is not available.
- On Linux, simplified the processing running BSK modules that require boost. This makes the Viz related communicaiton modules working again.
- Added boost libs built on Ubunutu against gcc 5.4.0 20160609.
- Added RPATH settings to allow for build directory to be placed outside source directory
- Major addition with new depleatable mass dynamic modeling, including some fuel tank dynamic models.
- minor fix for Monte Carlo dispersions
Initial limited public release.
Simulation modules include:
- Flexible integration structure with fixed time step RK1, RK2 and RK4 included
- Rigid spacecraft simulated through
spacecratPlus() module. The spacecraft object makes it simple to add external disturbances through
dynEffectors and state depended actuation through
- Dynamics Effectors (acuation methods which do not have their own states to integrate)
- External force or torque module
- Solar radiation pressure module
- Thruster module
- State Effectors (actuation methods which have states to integrate)
- Fuel Tank model with fuel slosh particles
- Hinged panel model to simulate flexing structures such as solar panels
- Reaction wheel module with 3 modes (perfectly balanced, simple jitter with the disturbance modeled as an external force and torque, fully coupled imbalanced RW model)
- RW voltage interface module that mapes an input voltage to a RW motor torque
- integrate Spice ephemeris information
- simple navigation module that produces the position and attitude measurement states
- IMU sensor
- Star Tracker module
- Coarse Sun Sensor (CSS) module
- Added the ability to simulate the gravity from multiple celestial objects, as well as include spherical harmonic expansion of a particular celestial body.
The AVS Lab Flight Algorithm folder contains:
- FSW template module
- CSS based sun heading estimation module
- UKF filter to determine inertial attitude
- UKF fitler to determine CSS based body-relative sun heading
- Attitude Guidance modules:
- Pointing towards two celestial objects
- Inertial Pointing
- Hill Frame Pointing
- Euler rotation sequence to add dynamics capabiliteis to the attitude reference generation
- Spinning about an inertially fixed axis
- A raster manager module that can change the guidance module states
- Velocity frame pointing
- attitude tracking error evaluation module
- Deadband module for attitude trackign error
- DV guidance module
- Effector Interfaces
- mapping of control torque onto RW motor torques
- Converting RW motor torques to voltages
- RW null motion module to equalize the wheel speeds continuously
- Thruster (THR) firing logic using a Schmitt trigger
- THR firign logic using a remainder calculation
- mappign of a command torque onto a set of THR devices
- module to evalute the net momentum to dump with thrusters