HowToMakeNewSimulationScenario.md

How To Make New Simulation Scenario

1. Overview

• In the Getting Started tutorial, we can directly build and execute s2e-core, but for source code sharing and practical usage of S2E, we strongly recommend managing s2e-core and s2e-user repository separately.
  • s2e-core repository is shared with other users. Most of the source files are in this core repository. The codes are used as a library by the s2e-user repository.
  • s2e-user repository is an independent repository for each spacecraft project or research project. This repository includes the following parts:
    • Source codes for the main function.
    • Source codes for simulation scenario.
    • Source codes for components if the target spacecraft has components, which strongly depends on your project.
    • Setting files to define detailed parameters for simulation settings.
    • Compile setting files as CMake files, Visual Studio Solution files, or others.
• This tutorial explains an example of how to make s2e-user repository and execute it.
• The supported version of this document
  • Please confirm that the version of the documents and s2e-core is compatible.

2. Structure of S2E-USER directory

• We provides a sample of a s2e-user repository as s2e-user-example.

• The repository is constructed as follows.

  • The repository includes s2e-core by using git submodule feature.
  • The ExtLibraries for the user side repository should be generated by using the CMake files in the s2e-core.

  └─ s2e-user-example
     └─ src
     └─ s2e-core (git submodule)
     └─ ExtLibraries (generated by the following procedure)
     └─ settings
     └─ logs
     └─ other files
  

3. Setup s2e-user-example

1. Clone s2e-user-example repository in a working directory.

   • Because the repository includes s2e-core with the git submodule, please use the following commands to construct the directory.

     $ git clone git@github.com:ut-issl/s2e-user-example.git
     $ cd s2e-user-example/
     $ git submodule init
     $ git submodule update
     

     Or use the following command to clone the repository.

     $ git clone --recursive git@github.com:ut-issl/s2e-user-example.git
     

2. Download mandatory ExtLibraries (CSPICE and NRLMSISE-00).

   • Users need to use the CMakeList.txt in the s2e-user-example/s2e-core/ExtLibraries to download the mandatory external libraries.
   • The construction procedure is same with the s2e-core. Please see a How To Build document suit with your platform.
     • Please carefully check the EXT_LIB_DIR and SETTINGS_DIR and change the path if needed.
   • Please check the following directories and files are made.

     └─ s2e-user-example
        └─ src
        └─ s2e-core (git submodule)
          └─ ExtLibraries
            └─ CMakeLists.txt (Use this file in this step)
        └─ ExtLibraries (This directory is generated by this step)
          └─ cspice
          └─ nrlmsise00
        └─ settings
          └─ environment
            └─ cspice
              └─ generic_kernels (This directory is generated by this step)
            └─ space_weather
              └─ SpaceWeather-v1.2.txt (This file is generated by this step)
        └─ logs
     

3. According to the How To Build document, use the s2e-user-example/CMakeList.txt and build the s2e-user.

4. Execute and check the s2e-user-example/logs.

5. Similar to Getting Started, you can edit initialize files in s2e-user-example/settings and check the log file.

Note: Users can use other characters instead of user for a practical case. For example, you can name it s2e_equuleus to indicate the EQUULEUS spacecraft project.

4. Overview of S2E-USER-EXAMPLE

• This chapter explains the overview of the main branch of the s2e-user-example.
• The files in the directory are as follows. From here, the detail of each file is described.

  └─ s2e-user-example
    └─ CMakeLists.txt  
    └─ CMakeSetting.json  
    └─ settings
    └─ logs
    └─ src  
      └─ simulation
        └─ case
          └─ user_case.cpp
          └─ user_case.hpp
        └─ spacecraft
          └─ user_components.cpp  
          └─ user_components.hpp
          └─ user_satellite.cpp
          └─ user_satellite.hpp
      └─ s2e_user.cpp
    └─ s2e-core (git submodule)  
  

1. CMakeLists.txt and CMakeSetting.json

   • CMakeLists.txt is a CMake file for a compile setting.
     • Details of description rules for CMake files can be searched on the internet, so please refer to them.
     • When you add new source files, the new files is automatically included as the build target. If you do not include them, please add them to excluding list in the CMakeList.txt.
   • CMakeSetting.json is a compile setting file for Visual Studio.

2. settings and logs

   • In the settings directory, there are several setting files to define the simulation parameters.
     • The most important setting file is user_simulation_base.ini.
     • Other setting files are defined in this base setting file. So you need to edit the file names in the base file when you modify the name of other setting files.
       • When you change the name of the base file, you have to edit s2e_user.cpp.
     • Details of the setting files are described in s2e-documents/Specifications.
       • Basic files are described in Getting Started.
   • logs
     • CSV log files will be outputted here. The output directory is also defined in user_simulation_base.ini, so that you can change it.

3. src/s2e_user.cpp

   • This is the main file of this program.
   • In this code, user_simulation_base.ini is defined as the base file for the simulation, and an instance of the SimulationCase class named UserCase is created and initialized. And finally, the main routine of the class is executed.

4. src/simulation/case/user_case.cpp, .hpp

   • UserCase class is defined here. UserCase class inherits the SimulationCase base class in the s2e-core. The SimulationCase class has a SimulationConfiguration and GlobalEnvironment class. The UserCase class has an instance of the spacecraft class named as UserSatellite.

5. src/simulation/spacecraft/user_satellite.cpp, .hpp

   • UserSatellite class is defined here. UserSatellite class inherits the Spacecraft class in the s2e-core. The Spacecraft base class has instances of Dynamics, LocalEnvironment, Disturbance, and Structure. And the UserSatellite class has an instance of UserComponents.

6. src/simulation/spacecraft/user_components.cpp, .hpp

   • The UserComponents class is defined here. Most users edit this code to custom the S2E for their satellite projects.
   • Users select components they want to use from the s2e-core/src/components.
   • You can add new source codes in the s2e-user/components directory if you want to make original components.