Overview¶
Prerequisites¶
Requires one of the following Python versions:
2.7 (Be aware that this version is officially depreciated from January 1, 2020.)
3.5
3.6
3.7
3.8
3.9
If you do not already have one of these versions available, we recommend installing it through Miniconda, as it provides an easy way of managing different Python versions and package environments.
Installation¶
If using Anaconda/Miniconda, make sure you have activated the environment you want to use. To install, simply run the following command in your terminal:
pip install ast2000tools
This will download and install the latest version of the package, along with any required extra packages.
Note: If you do not use a virtual Python environment like Anaconda/Miniconda, the default python command will typically correspond to Python 2.7, as will the default pip command. In this case you have to use the python3 and pip3 commands if you want to use Python 3.x. You can check the version by calling python --version.
Upgrading to a newer version¶
Simply run the installation command with an additional flag:
pip install --upgrade ast2000tools
In order to help you stay updated, ast2000tools provides a function in the utils module that you can use to check whether a newer version is available:
import ast2000tools.utils as utils
utils.check_for_newer_version()
Add this function call to the beginning of your code to make sure that you don’t miss out on any important updates!
Removal¶
When you are done with the course you probably want to remove the package. This is easy, just run the following command in your terminal:
pip uninstall ast2000tools
Getting started¶
The ast2000tools package contains tools required for the course AST2000 at the University of Oslo.
Here is an overview of the functionalities of the package. See the API reference for detailed documentation of all features.
constants¶
The constants module defines various physical and mathematical constants that you will need. Using these values will prevent any discrepancies between results due to differently defined constants, since these are also the values used internally in ast2000tools. The constants are consistent with the ones defined in the scipy.constants and astropy.constants modules.
import ast2000tools.constants as const
print('One astronomical unit is defined as', const.AU, 'meters.')
utils¶
The utils module contains a couple of general functions that you might find useful, for example the get_seed function that you will see in the next section.
SolarSystem¶
The SolarSystem class represents a procedurally generated solar system, with planets orbiting a central star. To initialize the solar system you provide a 5-digit seed that you generate from your UiO username as follows:
import ast2000tools.utils as utils
seed = utils.get_seed('<Your username>')
Now you can generate your system:
from ast2000tools.solar_system import SolarSystem
system = SolarSystem(seed)
The resulting system object holds a range of read-only properties of your solar system:
print('My system has a {:g} solar mass star with a radius of {:g} kilometers.'
.format(system.star_mass, system.star_radius))
for planet_idx in range(system.number_of_planets):
print('Planet {:d} is a {} planet with a semi-major axis of {:g} AU.'
.format(planet_idx, system.types[planet_idx], system.semi_major_axes[planet_idx]))
It also has some methods for verifying and visualizing your own trajectory simulations. For example, you can visualize the time evolution of your solar system as follows:
times, planet_positions = ... # Your own orbit simulation code
system.generate_orbit_video(times, planet_positions, filename='orbit_video.xml')
The generated file orbit_video.xml can be opened in the SSView application to render a realistic interactive 3D animation of your system.
SpaceMission¶
The SpaceMission class represents a mission to launch a spacecraft from your home planet (the planet with index 0), send it through your solar system and land it on a the surface of another planet. You initialize a mission with the seed generated from your username:
from ast2000tools.space_mission import SpaceMission
mission = SpaceMission(seed)
The resulting mission object holds a SolarSystem instance called system, representing the system in which the mission takes place:
home_planet_idx = 0 # The home planet always has index 0
print('My mission starts on planet {:d}, which has a radius of {:g} kilometers.'
.format(home_planet_idx, mission.system.radii[home_planet_idx]))
It also has a range of other attributes related to the mission:
print('My spacecraft has a mass of {:g} kg and a cross-sectional area of {:g} m^2.'
.format(mission.spacecraft_mass, mission.spacecraft_area))
Your progress through the stages of the mission will be kept track of:
if not mission.rocket_launched:
print('I have not launched the rocket yet. Let us do something about that!')
mission.launch_rocket()
SpaceMission instances can be saved to file in order for you to keep your progress between Python sessions:
SpaceMission.save('mission_after_launch.pickle', mission)
You can then load the instance again to continue where you left off:
mission = SpaceMission.load('mission_after_launch.pickle')
print('Look, I am still in space:', mission.rocket_launched)
InterplanetaryTravel¶
The InterplanetaryTravel class represents a particular part of your space mission, namely the journey of your spacecraft from your home planet to the destination planet. You initiate an interplanetary travel using your mission instance:
travel = mission.begin_interplanetary_travel()
A range of commands are available to send to the spacecraft. The trajectory can be controlled by performing boosts followed by periods of free-fall coasting:
travel.boost([0, 0.2]) # Boost to increase velocity by 0.2 AU/yr in the y-direction
travel.coast(0.3) # Let the spacecraft coast freely for 0.3 years
An orientation can be requested to obtain the current location and velocity of the spacecraft:
time, position, velocity = travel.orient() # Obtain coordinates relative to the star
The on-board camera can be used to record what is happening:
travel.look_in_direction_of_motion() # Make the camera track the direction of motion
travel.start_video() # Begin recording
travel.coast(0.1) # Coast for 0.1 years
travel.finish_video(filename='travel_video.xml') # Stop recording and store video file
The generated file travel_video.xml can be opened in the MCAst application to render a realistic 3D movie of what the spacecraft camera recorded.
LandingSequence¶
The LandingSequence class is very similar to the InterplanetaryTravel class. It represents the final and most critical part of the spacecraft’s journey: the landing on the destination planet.
The landing sequence can be initiated after the interplanetary travel is completed, in much the same manner as for the travel object:
landing = mission.begin_landing_sequence()
Before starting the landing procedure, landing aids like the parachute and landing thruster must be configured:
landing.adjust_parachute_area(42) # Set the parachute area to 42 m^2
landing.adjust_landing_thruster(force=500) # Set the thruster force to 500 Newtons
Maneuvering and orienting the spacecraft, as well as recording pictures and videos, works much like before:
landing.boost([0, -600, 0]) # Boost to decrease velocity by 600 m/s in the y-direction
landing.fall(800) # Let the spacecraft fall for 800 seconds
time, position, velocity = landing.orient() # Obtain coordinates relative to the planet
landing.look_in_direction_of_planet() # Make the camera track the destination planet
landing.take_picture(filename='landing_picture.xml') # Generate a still picture
When the spacecraft has been put safely into orbit, it is time to leave it behind and release the landing module:
landing.launch_lander([200, 0, 0]) # Launch the lander at 200 m/s in the x-direction
landing.fall(2000) # Let the lander fall for 2000 seconds
The landing object also has some attributes informing about the current status:
if not landing.parachute_deployed:
print('Whoops, forgot to deploy the parachute!')
landing.deploy_parachute()
The option to retry the landing might come in handy as well:
if landing.parachute_broken:
print('Ouch, that did not go so well. Maybe my planning simulation had a bug..')
print('Good thing I brought a spare lander!')
landing.restart()
SpaceMissionShortcuts¶
The SpaceMissionShortcuts class provides a set of shortcuts for you to use when you get stuck on some part of your space mission. It is important that you aim to keep up with the pace of the group sessions and not fall too far behind. Because of the limited time available, it is quite likely that you will need a shortcut at some point. When this happens, simply identify the shortcut(s) you will need in order to make progress, and request a code from the project group teacher (lars.frogner@astro.uio.no). Specify the name of the shortcut method as well as the seed value you are using.
Using a shortcut is easy. Just initialize a SpaceMissionShortcuts instance with your mission object and the relevant codes:
from ast2000tools.shortcuts import SpaceMissionShortcuts
codes = [12345] # The codes recieved from the group teacher (in this case just one)
shortcuts = SpaceMissionShortcuts(mission, codes)
Then you can call the shortcut method, in this case one that puts your spacecraft in orbit around the destination planet:
planet_idx = 4 # The destination planet
time = 4.0 # The time when the spacecraft should be placed in orbit
shortcuts.place_spacecraft_in_unstable_orbit(planet_idx, time)
Keep in mind that it is far better to make use of a shortcut than getting stuck and starting to lag behind. Whether or not your code actually produces the correct numbers only makes up a small fraction of your score on an exercise! The primary objective is for you to demonstrate physical understanding.
RelativityExperiments¶
The RelativityExperiments class lets you perform a range of experiments to explore the effects of special and general relativity. All the experiments take place in your procedurally generated solar system, so just like with the other classes you create an instance by providing your seed:
from ast2000tools.relativity import RelativityExperiments
experiments = RelativityExperiments(seed)
It is then a simple matter to run an experiment:
planet_idx = 4 # I want to perform the experiment near planet 4
experiments.cosmic_pingpong(planet_idx,
filename_1='cosmic_pingpong_frame_1.xml',
filename_2='cosmic_pingpong_frame_2.xml',
filename_3='cosmic_pingpong_frame_3.xml')
For this particular experiment, three XML video files are generated, each showing the chain of events from a different frame of reference. These can be opened and viewed in MCAst.
StarPopulation¶
The StarPopulation class can be used to generate a population of stars of different types, whose properties can be visualized in a Hertzsprung–Russell diagram.