Skymap

Skymap Diagram

OTSO.skymap

skymap(
    Stations: Union[str, Sequence[str]],
    customlocations: Optional[list] = None,
    solar_wind_params: SolarWindParams = {},
    geomagnetic_params: GeomagneticParams = {},
    tsyganenko_params: TsyganenkoParams = {},
    datetime_params: DateTimeParams = {},
    magfield_params: MagFieldParams = {},
    integration_params: IntegrationParams = {},
    particle_params: ParticleParams = {},
    rigidity_params: RigidityParams = {},
    coordinate_params: CoordinateParams = {},
    computation_params: ComputationParams = {},
    data_retrieval_params: DataRetrievalParams = {},
    custom_field_params: CustomFieldParams = {},
    skymap_params: SkymapParams = {},
) -> list

Compute geomagnetic cutoff rigidities over a range of zenith and azimuth combinations for given neutron monitor stations, or user-defined locations. Useful for showing the East-West asymmetry of cosmic-ray arrival.

Upon calling this function, OTSO will perform particle tracing simulations based on the specified parameters, returning the cutoff rigidities as functions of zenith and azimuth, and related metadata.

Parameters:

Stations (str | list) –

Station name(s) or identifiers used for cutoff calculations.
customlocations (list, default: None ) –

Custom locations as [["NAME", lat, lon]].
cutoff_comp (str) –

Cutoff computation method ("Vertical", "Apparent", "Custom").
datetime_params (DateTimeParams, default: {} ) –
Date/time parameters.

Available keys:
- year (int, default=2024): Year (e.g., 2023)
- month (int, default=1): Month (1–12)
- day (int, default=1): Day (1–31)
- hour (int, default=12): Hour (0–23)
- minute (int, default=0): Minute (0–59)
- second (int, default=0): Second (0–59)
magfield_params (MagFieldParams, default: {} ) –
Magnetic field models.

Available keys:
- internalmag (str, default="IGRF"): "NONE", "IGRF", "Dipole", "Custom Gauss", "CHAOS"
- externalmag (str, default="TSY89c"): "NONE", "TSY87short", "TSY87long", "TSY89a", "TSY96", "TSY01", "TSY01S", "TSY04", "TSY89c", "TSY15N", "TSY15B", "TA16_RBF", "TSY89_refit", "MHD"
- boberg (bool, default=False): Enable Boberg extension
- bobergtype (str, default="EXTENSION"): "EXTENSION", "CONTINUOUS", "DST_DEPENDENT", "DST_MIDPOINT"
- magnetopause (str, default="Kobel"): "NONE", "Kobel", "Sibeck", "Lin", "Sphere", "aFormisano"
- spheresize (float, default=25): Spherical boundary radius (Re)
- AdaptiveExternalModel (bool, default=False): Auto-select external model
rigidity_params (RigidityParams, default: {} ) –
Rigidity scanning.

Available keys:
- startrigidity (float, default=20): Initial rigidity (GV)
- endrigidity (float, default=0): Final rigidity (GV)
- rigiditystep (float, default=0.01): Step size (GV)
- rigidityscan (str, default="ON"): Enable scanning ("ON"/"OFF")
skymap_params (SkymapParams, default: {} ) –
Sky map zenith and azimuth resolution parameters

Available keys:
- zenithstep (float, default=15): Zenith resolution
- azimuthstep (float, default=45): Azimuth resolution
- maxzenith (float, default=75): Maximum deviation from the zenith
- minzenith (float, default=0): Minimum deviation from the zenith
- maxazimuth (float, default=360): Maximum azimuth value
- minazimuth (float, default=0): Minimum azimuth value
solar_wind_params (SolarWindParams, default: {} ) –
Solar wind parameters.

Available keys:
- vx (float, default=-500): Solar wind velocity x-component (km/s)
- vy (float, default=0): Solar wind velocity y-component (km/s)
- vz (float, default=0): Solar wind velocity z-component (km/s)
- bx (float, default=0): IMF x-component (nT)
- by (float, default=5): IMF y-component (nT)
- bz (float, default=5): IMF z-component (nT)
- by_avg (float, default=0): Averaged IMF By over last 30mins (nT)
- bz_avg (float, default=0): Averaged IMF Bz over last 30mins (nT)
- density (float, default=1): Solar wind density (particles/cm³)
- pdyn (float, default=0): Solar wind dynamic pressure (nPa)
geomagnetic_params (GeomagneticParams, default: {} ) –
Geomagnetic indices.

Available keys:
- Dst (float, default=0): Dst index (nT)
- kp (float, default=0): Kp index (0-9)
- n_index (float, default=0): Newell coupling function
- b_index (float, default=0): Boynton coupling function
- sym_h_corrected (float, default=0): Corrected SYM-H index (nT)
tsyganenko_params (TsyganenkoParams, default: {} ) –
Tsyganenko model coefficients.

Available keys:
- G1 (float, default=0): Tsyganenko G1 coefficient
- G2 (float, default=0): Tsyganenko G2 coefficient
- G3 (float, default=0): Tsyganenko G3 coefficient
- W1 (float, default=0): Tsyganenko W1 coefficient
- W2 (float, default=0): Tsyganenko W2 coefficient
- W3 (float, default=0): Tsyganenko W3 coefficient
- W4 (float, default=0): Tsyganenko W4 coefficient
- W5 (float, default=0): Tsyganenko W5 coefficient
- W6 (float, default=0): Tsyganenko W6 coefficient
integration_params (IntegrationParams, default: {} ) –
Integration settings.

Available keys:
- intmodel (str, default="Boris-Buneman"): "4RK", "5RK", "6RK", "Vay", "HC", "Boris-Buneman"
- gyropercent (float, default=15): Gyration period percentage
- minaltitude (float, default=20): Minimum altitude (GDZ = km or other = Re)
- maxdistance (float, default=100): Maximum distance (Re)
- maxtime (float, default=0): Maximum time
- mintrapdist (float, default=0): Minimum trapping distance
- startaltitude (float, default=20): Starting altitude (GDZ = km or other = Re)
- betaerror (float, default=0.001): Maximum allowed beta error for integration steps %
- totalbetacheck (bool, default=False): Enable cumulative beta check during integration
- adaptivestep (bool, default=True): Enable adaptive time steps
- maxsteps (int, default=None): Maximum number of integration steps
particle_params (ParticleParams, default: {} ) –
Particle settings.

Available keys:
- Anum (int, default=1): Atomic number (-1=muon, 0=electron, 1=proton, 2=alpha)
- anti (str, default="YES"): YES = anti-particle, NO = particle
coordinate_params (CoordinateParams, default: {} ) –
Coordinate systems.

Available keys:
- inputcoord (str, default="GDZ"): Input coordinate system; "GDZ", "GEO", "GSM", "GSE", "SM", "GEI", "MAG", "SPH", "RLL"
computation_params (ComputationParams, default: {} ) –
Computation settings.

Available keys:
- corenum (int, default=None): Number of CPU cores for multicore processing
- threadnum (int, default=None): Number of threads per CPU core for Fortran computations
- Verbose (bool, default=True): Enable verbose output
data_retrieval_params (DataRetrievalParams, default: {} ) –
Data retrieval.

Available keys:
- serverdata (str, default="OFF"): Server data retrieval from OMNI
- livedata (str, default="OFF"): real-time data retrieval from NOAA
custom_field_params (CustomFieldParams, default: {} ) –
Custom fields.

Available keys:
- g (list, default=None): Gauss g coefficients
- h (list, default=None): Gauss h coefficients
- max_degree (int, default=13): Max degree of spherical harmonic expansion
- MHDfile (str, default=None): MHD simulation file
- MHDcoordsys (str, default=None): MHD coordinate system

Returns:

list ( list ) –
[skymap_dataframe, readme_text]
- skymap_dataframe: Cutoff data values per input station and zenith and azimuth combination in a pandas dataframe. (Ru, Rc, Rl, PTF)
- readme_text: OTSO computation summary

Examples:

    import OTSO

    if __name__ == "__main__":

        stations = ["ROME"] # list of neutron monitor stations (using their abbreviations)

        # Using parameter groups
        skymap_results = skymap(
            Stations=stations,
            computation_params={"corenum": 1,"threadnum": 8},
            datetime_params={"year": 2005,"month": 5,"day": 1,"hour": 0},
            integration_params={"gyropercent": 10},
            magfield_params={"internalmag": "IGRF","externalmag": "NONE"},
            rigidity_params={"rigiditystep": 0.01},
            skymap_params={"zenithstep": 5,"azimuthstep": 15}
        )

        # Access the results
        skymap_data, metadata = result