lanl / ram-scb Goto Github PK

RAM-SCB is a unique code that combines a kinetic model of ring current plasma with a three dimensional force-balanced model of the terrestrial magnetic field to simulate Earth's inner magnetosphere.

License: Other

Perl 6.50% Makefile 0.77% Python 1.32% Fortran 89.61% Shell 0.79% HTML 0.18% C++ 0.08% C 0.35% Dockerfile 0.01% Roff 0.12% Raku 0.27%

magnetosphere physics-simulation space-physics fortran2008

ram-scb's Introduction

RAM-SCB

The Ring current Atmosphere interactions Model with Self Consistent magnetic field (B) is a unique code that combines a kinetic model of ring current plasma with a three dimensional force-balanced model of the terrestrial magnetic field. The kinetic portion, RAM, solves the kinetic equation to yield the bounce-averaged distribution function as a function of azimuth, radial distance, energy and pitch angle for three ion species (H+, He+, and O+) and, optionally, electrons. The 3-D force balanced magnetic field model, SCB, balances the J × B force with the divergence of the general pressure tensor to calculate the magnetic field configuration within its domain. The two codes work in tandem, with RAM providing anisotropic pressure to SCB and SCB returning the self-consistent magnetic field through which RAM plasma is advected. RAM-SCB has grown from a research-grade code with limited options and static magnetic field (RAM) to a rich, highly configurable research and operations tool with a multitude of new physics and output products. The RAM-SCB manual provides a guide to users who want to learn how to install, configure, and execute RAM-SCB simulations. While the code is designed to make these steps as straight-forward as possible, it is strongly recommended that users review the publications listed in the Bibliography to ensure a thorough understanding of the physics included in the model.

Documentation

The RAM-SCB manual with extended installation and usage information can be found at RAM-SCB/doc/RAM_SCB.pdf.

Attribution

Researchers who use the RAM-SCB code for scientific research are asked to cite the papers listed below.

Engel, M. A., Morley, S. K., Henderson, M. G., Jordanova, V. K., Woodroffe, J. R., & Mahfuz, R. (2019). Improved simulations of the inner magnetosphere during high geomagnetic activity with the RAM-SCB model. Journal of Geophysical Research: Space Physics, 124, 4233–4248. doi:10.1029/2018JA026260
Jordanova, V. K., S. Zaharia, and D. T. Welling (2010), Comparative study of ring current development using empirical, dipolar, and self-consistent magnetic field simulations, J. Geophys. Res., 115(A14):A00J11, doi:10.1029/2010JA015671.
Welling, D. T., V. K. Jordanova, S. G. Zaharia, A. Glocer, and G. Toth (2011), The effects of dynamic ionospheric outflow on the ring current, J. Geophys. Res., 116, doi:10.1029/2010JA015642.
Jordanova, V. K. et al. (2006), Kinetic simulations of ring current evolution during the Geospace Environment Modeling challenge events, J. Geophys. Res., 111, A11S10, doi:10.1029/2006JA011644.

Installation

For full installation details, please see the documentation folder.

To install on Linux (or similar), three main steps are required:

Install prerequisites

Fortran/C/C++ compilers are required, we recommend gfortran/gcc/g++
GSL is required
NetCDF-Fortran is required
Perl is required (standard on most linux systems)

Configure the build

Setup is done using the Config.pl Perl script. This sets up the make system and tells RAM-SCB where to find its dependencies.
An example setup: ./Config.pl -install -compiler=gfortran -mpi=openmpi -openmp -ncdf -gsl
If Config.pl shows the warning "Can't locate share/Scripts/Config.pl in @INC" then add the RAM-SCB directory to the Perl path. In bash this is done with export PERL5LIB=`pwd`
Most installations of NetCDF4 and GSL should come with command line utilities to help determine library locations and flags. To auto-detect these use the -ncdf and -gsl flags without specifying a library location.

Compile the code

Simply run make. If you have multiple cores available for compilation then you can speed things up by running make -j

Usage

make rundir RUNDIR=~/desired_run_directory
./ram_scb.exe

Release

This software has been approved for open source release and has been assigned LA-CC-16-077.

License

The RAM-SCB License can be found at RAM-SCB/LICENSE.txt.

Contact

For questions about using RAM-SCB please contact Vania Jordanova.

ram-scb's People

Contributors

Stargazers

Watchers

Forkers

louisvernon drsteve yangjian615 pheosics spacecataz vaniakj xuliu1 rmahfuz galaxyfollower yiqunyu 5l1v3r1 hcgodinez mudtop katmipt zhaomingxian sgraf95 saturnem amadibrians syygdx

ram-scb's Issues

Clean-up required after new CI

The new CI replaces our old, defunct Travis CI.
Two things still need to happen:

The CI badge in README.md needs to be updated to point to the GitHub actions outcome.
The .travis.yml file needs to be removed and any Travis integration turned off.

Add LACC number

We need the LACC number in the README.md

CI needs updating/migrating

Possible issues:

Travis CI are migrating everything from their .org domain to .com
Travis CI have dropped useful OSS support, so we'll likely run out of credits for CI in the not-too-distant future
Our docker container uses Ubuntu 16.04 (which is now EOL) and GCC5 (which is ancient)

Actions required:

Check whether we need to do anything to prevent CI breaking when Travis migrates/shuts down the .org service
Consider the long term plan. Probably best to move to github actions, but CircleCI or similar might be a good option
Update the docker container to a recent Ubuntu LTS and GCC (probably 9 or 10)

IGRF/DGRF files for IRI are not copied into run directory

The IRI requires the igrf*.dat and dgrf*.dat files to work correctly. These are in the input directory but are not copied over to the run directory when make rundir is called.

(See also #92 as the IRI we include is, I think, fairly out of date)

Improve compile/install as SWMF component

Currently installing as part of the SWMF requires making a number of changes manually that should be automated, or otherwise handled:

Commenting out PLE_OBJECTS in ModRamRun.f90
Commenting out the DoUsePlane_SCB IF block in src/Makefile
Removing the share directory
Manually changing paths in both Makefile.conf and Makefile.def

Using with SWMF should be easier out-of-the-box and minimizing the amount of manual editing is highly desirable.

SWMF/share library is out of date

The bundled share library is out of date and incompatible with GCC10.
In particular, the make_dir subroutine in share/Library/src/ModUtility.f90 sets an octal permission mask. This is no longer allowed under GCC10, but the routine has already been rewritten in the upstream repo (and actually has a different calling syntax).

The share folder should be updated to the latest version from SWMF.

RAM-SCB won't compile under GCC10

Two issues here:

As noted in #78 the share library is out of date. One of the changes removes setting an octal mask which is now prohibited under GCC10. This can be solved in the short term by adding the -fallow-invalid-boz flag, but this flag (if added) should be removed when the share library is updated.
Interfaces in our dependencies now trigger a strict check for argument mismatches, leading compilation to fail. Under GCC10 these can be converted to warnings by adding a new flag: -fallow-argument-mismatch.

Travis CI should run all tests

Presently the Travis CI seems to only run one test (test 3?)
All tests should actually work, and so all should be run when pull requests are sent.

Test suite needs expanding

Currently the CI only runs what amounts to test 3. GitHub Actions gives us ~2000 minutes per month for CI and the max runtime of a single container is ~hours.

I'd suggest perhaps switching back to either the "long" CI test or running tests 1 through 3. As long as total test time stays under an hour we should be fine, even during fairly heavy development bursts... ideally we'd run our different tests in parallel and then check test status based on whether they all pass (e.g., the way SpacePy does it)

It's also a good idea to plan out proper unit tests, but expanding the coverage of our regression and integration tests is the low hanging fruit.

ModRamFunctions needs legacy control structure updating

While we can't necessarily control some of our dependencies, there are still a couple of GOTO statements in the codebase (ModRamFunctions.f90). These are coupled with DO [line number] ... CONTINUE loop control, and can be rewritten to conform to modern Fortran standards.

These are an ideal case for some unit tests. So first we can write unit tests for functions with old-style control flow (and make sure that the tests are thorough and pass), then update the functions to use modern approaches.

Incorrect dimensionality on omni flux in satellite output files

Current virtual satellite output NetCDF files make omnidirectional flux variables that are 3D (energy, pitch angle, time), where they should be 2D as the variable is integrated over pitch angle.

The 3D array is created on line 403 of ModRamSats.f90.
It is populated as 2D on line 755 of ModRamSats.f90

@Pheosics : Am I right in thinking this is going to be as simple to fix as changing the dimensionality of the array back to 2D when it's created?

Random Segmentation faults

Hi,

I am running RAM-SCB for several days (simulation time) and it sometimes randomly crashes with a segfault. I have found that rerunning the simulation several times until it can finally end is my best solution for right now. I unfortunately cannot make a minimal reproducible example. This was compiled using GSL v2.7. Below is the segfault message and PARAM.in file:

stderr:

Program received signal SIGSEGV: Segmentation fault - invalid memory reference.

Backtrace for this error:
#0  0x2b713ce7862f in ???
#1  0x2b713ba49cd8 in gsl_spline_init
	at ../../interpolation/spline.c:72
#2  0x5e87db in ???
#3  0x4991c8 in ???
#4  0x4ed8d3 in ???
#5  0x4b950b in ???
#6  0x4918f7 in ???
#7  0x404cb4 in ???
#8  0x404ab6 in ???
#9  0x2b713d0a7554 in ???
#10  0x404ae6 in ???
#11  0xffffffffffffffff in ???

PARAM.in:

PARAM File for Test Week 05 Simulation
Derived from PARAM.in.default

#DESCRIPTION
Test_Week05: 2005-05-12

#EVENT
test_week05_final

************** REQUIRED BLOCK *****************
#STARTTIME
2005					iYear
5						iMonth
12						iDay
00						iHour
00						iMinute
0						iSecond
0.0						FracSecond

#STOPTIME
2005					iYear
5						iMonth
18						iDay
23						iHour
59						iMinute
59						iSecond
0.0						FracSecond

***********************************************

*************** TIMING BLOCK ******************
#MAXTIMESTEP
20.0			MaxHalfStep

#MINTIMESTEP
0.01			MinHalfStep

#VARIABLEDT
T			DoVarDt

#COMPONENT_TIMESTEPS
300.0			SCBTimeStep
300.0			BCTimeStep
300.0			EFTimeStep

***********************************************

*************** COMPONENT BLOCK ***************
#OUTERBOUNDARY
LANL			NameBoundPlasma
T89D			NameBoundMag
MAXW			NameDistribution

#EFIELD
WESC			NameEfield
F				UseEfInd

***********************************************

***************** RAM BLOCK *******************


***********************************************

***************** SCB BLOCK *******************
#SCBFLAGS
F			Isotropic
F			ReduceAnisotropy
T			BetaExtrapolation
F			AzimuthalOffset
F			EmptyLossCone
T			AdaptiveMesh


#SCBSMOOTHING
1			PressureSmoothing
3			SavitzyGolayIterations

***********************************************

***************** INPUT BLOCK *****************
#OMNIFILE
omni.txt		NameOmniFile

#OMNIFILESOURCE
T			UseSWMFFormat

#INDICES_FILE
RamIndices.txt		NameIndicesFile

***********************************************

***************** OUTPUT BLOCK ****************
#SAVERESTART
3600.0			DtSaveRestart
T			DoSaveFinalRestart

#TIMEDRESTART
F			TimedRestartFiles

#LOGFILE
600.0			DtLogFileWrite

#SAVEFLUX
600.0			DoSaveFlux

#OUTPUT_FREQUENCY
-1			DtPressureFileWrite
-1			DthIFileWrite
-1			DtEFieldFileWrite
-1			DtMAGxyzFileWrite

#DUMP3DFLUX
F			DoDump3DFlux

***********************************************

Thank you for your time.

Update dependent models/libraries in srcExternal

srcExternal includes IRI and GEOPACK. Both appear to be pretty well out of date.

We should probably have a test that engages code calling these, and then we should update to recent versions.
IRI source: http://irimodel.org/IRI-2016/
GEOPACK source: http://geo.phys.spbu.ru/~tsyganenko/Geopack-2008_dp.for

Obsolete data and test output should be removed

The output directory contains a folder test9, which is for a test that hasn't existed in the version control history that I have access to (i.e., at least since November 2009). This should be removed.

Electric/magnetic field options need updating in documentation

The current docs only list:

IESC : for use in SWMF
VOLS : Volland-Stern
WESC : Weimer (where the reference is given in PARAM.xml as both 2000 and 2001)

Options W5SC (Weimer 2005) and RSCE (self-consistent E) do not appear to be documented anywhere.

~~This can probably be addressed in #75~~

Streamline dependencies and build, de-duplicate IRI

SCE adds new dependencies (GLOW) as well as duplicating current dependencies (IRI).
Ideally the SCE dependencies should all be in srcExternal and we should have no duplication. The IRI for GLOW/SCE also has its own input files that are duplicates of the IRI input files in the main input folder. This may require some work to streamline the build and ensure that all input files are moved into run directories correctly.