sscws Magnetic Field Line Trace Example Jupyter Notebook

This Jupyter notebook demonstrates using the sscws Python package to access satellite location and (modeled) magnetic field-line tracing information. It also demonstrates how to handle an error and display the error message when an invalid request is made. This notebook contains the following sections:

1. Prerequisites
2. Setup
3. Define a magnetic field line trace request
4. Get Locations
5. Error Handling
6. Additional Documentation

Prerequisites

Install the prerequisite software from the Python Package Index if it is not already installed.

#%pip install -U sscws

Setup

Execute some preliminary code that is necessary before the code that follows.

from sscws.sscws import SscWs
from sscws.bfieldmodels import BFieldModel, Tsyganenko89cBFieldModel
from sscws.coordinates import CoordinateComponent, CoordinateSystem,\
    SurfaceGeographicCoordinates
from sscws.filteroptions import LocationFilterOptions,\
    MappedRegionFilterOptions, RegionFilterOptions,\
    SpaceRegionsFilterOptions
from sscws.outputoptions import CoordinateOptions, BFieldTraceOptions,\
    DistanceFromOptions, LocationFilter, OutputOptions, RegionOptions,\
    ValueOptions
from sscws.regions import Hemisphere, HemisphereRegions
from sscws.request import DataRequest, SatelliteSpecification
from sscws.timeinterval import TimeInterval
ssc = SscWs()

Define a magnetic field line trace request

The following code defines a request for many values including magnetic field line tracing.

    sats = [SatelliteSpecification('themisa', 2)]

    b_field_model = BFieldModel(external=Tsyganenko89cBFieldModel())
    coord_options = [
        CoordinateOptions(CoordinateSystem.GSE, CoordinateComponent.X),
        CoordinateOptions(CoordinateSystem.GSE, CoordinateComponent.Y),
        CoordinateOptions(CoordinateSystem.GSE, CoordinateComponent.Z),
        CoordinateOptions(CoordinateSystem.GSE, CoordinateComponent.LAT),
        CoordinateOptions(CoordinateSystem.GSE, CoordinateComponent.LON),
        CoordinateOptions(CoordinateSystem.GSE, CoordinateComponent.LOCAL_TIME)
        ]
    b_field_trace_options = [
        BFieldTraceOptions(CoordinateSystem.GEO, Hemisphere.NORTH,
                           True, True, True),
        BFieldTraceOptions(CoordinateSystem.GEO, Hemisphere.SOUTH,
                           True, True, True)
        ]

    output_options = OutputOptions(
        coord_options,
        None, None,
        RegionOptions(True, True, True, True),
        ValueOptions(True, True, True, True),
        DistanceFromOptions(True, True, True, True),
        b_field_trace_options
        )
    loc_filter = LocationFilter(0, 100000, True, True)

    hemisphere_region = HemisphereRegions(True, True)
    trace_regions = MappedRegionFilterOptions(hemisphere_region,
                                              hemisphere_region,
                                              hemisphere_region,
                                              hemisphere_region,
                                              hemisphere_region,
                                              True)
    srfo = SpaceRegionsFilterOptions(True, True, True, True, True, True,
                                     True, True, True, True, True)

    rfo = RegionFilterOptions(srfo, trace_regions, trace_regions)

    format_options = None
    
    loc_request = DataRequest('themisa b-trace locator request.',
                              TimeInterval('2020-10-02T00:00:00Z',
                                           '2020-10-02T00:10:00Z'),
                              sats, b_field_model,
                              output_options, None,
                              None, format_options)

Get Locations

The following code submits the request created above to the SSC server and displays the results.

result = ssc.get_locations(loc_request)
if result['HttpStatus'] == 200:
    SscWs.print_locations_result(result)
else:
    print('ssc.get_locations failed with status = ', result['HttpStatus'])
    if 'ErrorMessage' in result:
        print('ErrorMessage = ', result['ErrorMessage'])
        print('ErrorDescription = ', result['ErrorDescription'])
    else:
        print('HttpText = ', result['ErrorText'])

themisa Gse
Time                      X                      Y                      Z                     
2020-10-02 00:00:00+00:00 25391.88098727723 76038.43619724039 17541.7997889056
2020-10-02 00:02:00+00:00 25311.055308443832 76129.3806396425 17540.543107991354
2020-10-02 00:04:00+00:00 25230.012585797875 76219.59380941694 17539.064278511694
2020-10-02 00:06:00+00:00 25148.727958863146 76308.92368175219 17537.406958795487
2020-10-02 00:08:00+00:00 25067.11881894818 76397.48618096307 17535.613675572848
2020-10-02 00:10:00+00:00 24985.290906646485 76485.30788933998 17533.59663819248
Geo North Magnetic Field-Line Trace Footpoints
Time                           Latitude         Longitude    Arc Length
2020-10-02 00:00:00+00:00             nan             nan             nan
2020-10-02 00:02:00+00:00             nan             nan             nan
2020-10-02 00:04:00+00:00             nan             nan             nan
2020-10-02 00:06:00+00:00             nan             nan             nan
2020-10-02 00:08:00+00:00             nan             nan             nan
2020-10-02 00:10:00+00:00             nan             nan             nan
Geo South Magnetic Field-Line Trace Footpoints
Time                           Latitude         Longitude    Arc Length
2020-10-02 00:00:00+00:00       -69.81784       168.72221    121605.15746
2020-10-02 00:02:00+00:00       -69.74149       168.46269    121638.26077
2020-10-02 00:04:00+00:00       -69.66567       168.20421    121668.47797
2020-10-02 00:06:00+00:00       -69.59042       167.94714    121695.10663
2020-10-02 00:08:00+00:00       -69.51577       167.69150    121718.42499
2020-10-02 00:10:00+00:00       -69.44167       167.43703    121738.81353
Time                      RadialLength
2020-10-02 00:00:00+00:00 82062.81806431271
2020-10-02 00:02:00+00:00 82121.87734979142
2020-10-02 00:04:00+00:00 82180.28206903554
2020-10-02 00:06:00+00:00 82237.89250694639
2020-10-02 00:08:00+00:00 82294.79969878629
2020-10-02 00:10:00+00:00 82351.04167902487
Time                      MagneticStrength
2020-10-02 00:00:00+00:00 31.813957039877756
2020-10-02 00:02:00+00:00 31.804102757778182
2020-10-02 00:04:00+00:00 31.795120441618316
2020-10-02 00:06:00+00:00 31.787039602521645
2020-10-02 00:08:00+00:00 31.779783334298298
2020-10-02 00:10:00+00:00 31.77338475318872
Time                      NeutralSheetDistance
2020-10-02 00:00:00+00:00 -1e+31
2020-10-02 00:02:00+00:00 -1e+31
2020-10-02 00:04:00+00:00 -1e+31
2020-10-02 00:06:00+00:00 -1e+31
2020-10-02 00:08:00+00:00 -1e+31
2020-10-02 00:10:00+00:00 -1e+31
Time                      BowShockDistance
2020-10-02 00:00:00+00:00 -42794.684772843706
2020-10-02 00:02:00+00:00 -42819.04155897035
2020-10-02 00:04:00+00:00 -42843.990692614556
2020-10-02 00:06:00+00:00 -42869.616659119936
2020-10-02 00:08:00+00:00 -42895.578961354266
2020-10-02 00:10:00+00:00 -42921.74402840615
Time                      MagnetoPauseDistance
2020-10-02 00:00:00+00:00 -238.04246637642478
2020-10-02 00:02:00+00:00 -224.52115205570763
2020-10-02 00:04:00+00:00 -211.31300208932416
2020-10-02 00:06:00+00:00 -198.97172601398145
2020-10-02 00:08:00+00:00 -187.45872025079237
2020-10-02 00:10:00+00:00 -176.69914710596737
Time                      DipoleLValue
2020-10-02 00:00:00+00:00 12.90922030614532
2020-10-02 00:02:00+00:00 12.920001852521048
2020-10-02 00:04:00+00:00 12.930719164789712
2020-10-02 00:06:00+00:00 12.941349401456149
2020-10-02 00:08:00+00:00 12.951906825744155
2020-10-02 00:10:00+00:00 12.962399896923625
Time                      DipoleInvariantLatitude
2020-10-02 00:00:00+00:00 73.83982
2020-10-02 00:02:00+00:00 73.846756
2020-10-02 00:04:00+00:00 73.85363
2020-10-02 00:06:00+00:00 73.86044
2020-10-02 00:08:00+00:00 73.8672
2020-10-02 00:10:00+00:00 73.87392
Time                      SpacecraftRegion
2020-10-02 00:00:00+00:00 SpaceRegion.DAYSIDE_MAGNETOSPHERE
2020-10-02 00:02:00+00:00 SpaceRegion.DAYSIDE_MAGNETOSPHERE
2020-10-02 00:04:00+00:00 SpaceRegion.DAYSIDE_MAGNETOSPHERE
2020-10-02 00:06:00+00:00 SpaceRegion.DAYSIDE_MAGNETOSPHERE
2020-10-02 00:08:00+00:00 SpaceRegion.DAYSIDE_MAGNETOSPHERE
2020-10-02 00:10:00+00:00 SpaceRegion.DAYSIDE_MAGNETOSPHERE
Time                      RadialTracedFootpointRegions
2020-10-02 00:00:00+00:00 FootpointRegion.LOW_LATITUDE
2020-10-02 00:02:00+00:00 FootpointRegion.LOW_LATITUDE
2020-10-02 00:04:00+00:00 FootpointRegion.LOW_LATITUDE
2020-10-02 00:06:00+00:00 FootpointRegion.LOW_LATITUDE
2020-10-02 00:08:00+00:00 FootpointRegion.LOW_LATITUDE
2020-10-02 00:10:00+00:00 FootpointRegion.LOW_LATITUDE
Time                      NorthBTracedFootpointRegions
2020-10-02 00:00:00+00:00 FootpointRegion.NOT_APPLICABLE
2020-10-02 00:02:00+00:00 FootpointRegion.NOT_APPLICABLE
2020-10-02 00:04:00+00:00 FootpointRegion.NOT_APPLICABLE
2020-10-02 00:06:00+00:00 FootpointRegion.NOT_APPLICABLE
2020-10-02 00:08:00+00:00 FootpointRegion.NOT_APPLICABLE
2020-10-02 00:10:00+00:00 FootpointRegion.NOT_APPLICABLE
Time                      SouthBTracedFootpointRegions
2020-10-02 00:00:00+00:00 FootpointRegion.SOUTH_AURORAL_OVAL
2020-10-02 00:02:00+00:00 FootpointRegion.SOUTH_AURORAL_OVAL
2020-10-02 00:04:00+00:00 FootpointRegion.SOUTH_AURORAL_OVAL
2020-10-02 00:06:00+00:00 FootpointRegion.SOUTH_AURORAL_OVAL
2020-10-02 00:08:00+00:00 FootpointRegion.SOUTH_AURORAL_OVAL
2020-10-02 00:10:00+00:00 FootpointRegion.SOUTH_AURORAL_OVAL
Time                              B Strength GSE        
                              X         Y         Z    
2020-10-02T00:00:00+00:00 -5.194202  1.483673 31.351983
2020-10-02T00:02:00+00:00 -5.271438  1.605927 31.323057
2020-10-02T00:04:00+00:00 -5.349014  1.727925 31.294281
2020-10-02T00:06:00+00:00 -5.426896  1.849599 31.265695
2020-10-02T00:08:00+00:00 -5.505079  1.970929 31.237224
2020-10-02T00:10:00+00:00 -5.583592  2.091986 31.208894

Error Handling

The following code creates an invalid request and demonstrates how to display the error message.

# add a duplicate option to cause an error
coord_options.insert(4, CoordinateOptions(CoordinateSystem.GSE, CoordinateComponent.LAT))

loc_request = DataRequest('themisa b-trace locator request.',
                          TimeInterval('2020-10-02T00:00:00Z',
                                       '2020-10-02T00:10:00Z'),
                           sats, b_field_model,
                           output_options, None,
                           None, format_options)
result = ssc.get_locations(loc_request)
if result['HttpStatus'] == 200:
    SscWs.print_locations_result(result)
else:
    print('ssc.get_locations failed with status = ', result['HttpStatus'])
    if 'ErrorMessage' in result:
        print('ErrorMessage = ', result['ErrorMessage'])
        print('ErrorDescription = ', result['ErrorDescription'])
    else:
        print('HttpText = ', result['ErrorText'])

ssc.get_locations failed with status =  400
ErrorMessage =  Invalid Request.
ErrorDescription =  4th coordinate listing option is a duplicate of an earlier option

Additional Documentation

View the sscws API for additonal features. Additional notebook examples are also available.