Introduction
PyBAMOCS uses a simplified box model to simulate the Atlantic meridional overturning circulation (AMOC) simulation, used by Gnanadesikan et al.1 to examine the stability of the AMOC. This code facilitates experimenting with the box model, including:
Documented API for running individual box model simulations
Generating data from many box model simulations
Storing box model data in NetCDF format
License
Copyright 2022, The Johns Hopkins University Applied Physics Laboratory LLC
All rights reserved.
Distributed under the terms of the BSD 3-Clause License.
Requirements
This code is tested on Python version 3.9
. The box model code also
leverages the following packages: - numpy
- seawater
-
matplotlib
- netCDF4
- pytest
(for running unit tests)
Getting Started
Python
If you are unfamiliar with Python, we recommend downloading Anaconda from here. Follow the instructions to install Anaconda, and then create a new conda environment (or virtual environment if not using Anaconda) by running
$ conda create -n <environment name> python==3.9
Follow the prompts to finish creating the new environment. Once finished, activate the environment via the following command:
$ conda activate <environment name>
The name of your environment should be in front of your command line, for example if you named your environment “myenv”, it should appear as follows:
(myenv) $
Running the code
Assuming you have the code pulled from the repository, navigate to the
pybamocs
directory and run
$ pip install -e .
This should install the required packages to run the Box model code in your Python environment. Once installed, you should be able to run the follow scripts from the scripts directory:
simple_example.py: An example of how to run a single box model simulation. Also creates plots of the results.
collapse_example.py: Several examples of AMOC collapse with plotted results.
store_example_npz.py: An example of how one might save box model data as Numpy
.npz
files.store_example_netcdf.py: An example of how one might save box model data in NetCDF format.
datagen_simulation.py: A script simulating a parameter space exploration experiment using small random perturbations on box model variables. Each simulation result is stored in NetCDF format.
Box model example
The very basic example of running the box model can be illustrated in the following example:
from pybamocs.box_model import box_model
from pybamocs.box_model_args import (
BoxModelBoxDimensions,
BoxModelInitConditions,
BoxModelParameters,
BoxModelTimeStep
)
# Define box model arguments (see definitions of each argument for available parameters and default settings):
box_dimensions = BoxModelBoxDimensions()
box_initial_conditions = BoxModelInitConditions()
box_parameters = BoxModelParameters(M_ek=35e6)
box_time_step = BoxModelTimeStep(n_steps=100)
# the box model returns a BoxModelResult object
result = box_model(box_dimensions, box_initial_conditions, box_parameters, box_time_step)
# Call the `unpack` method to get the various result values (if desired):
M_n, M_upw, M_eddy, D_low, T, S, sigma0 = result.unpack()
Organization
python
│ scripts - Location for local code examples and other useful scripts
│ notebooks - Location for Jupyter Notebooks
| setup.py - Installation script for module (typically associated with `pip install`)
| README.md - This file
│ tests - Location for test scripts
└───pybamocs - Top level Python module
└───test - Location of test scripts
└───data - Directory of files used for test
| box_model.py - box model code
| box_model_args.py - box model box model argument objects
| box_storage.py - functions for storing box model data to disk
| constants.py - various constants used between box model files
For Developers
When contributing to this code, we ask: - Start by creating a branch of
the repository, then writing the code, and creating a merge request -
Consider creating an issue on GitHub for more in-depth or challenging
additions or problems - Please use type hinting for arguments and
results - Remember to add the copyright statement at the top of the file
- Add unit tests where feasible (using pytest
) to the test
directory, and briefly describe the tests below
Running the tests
As previously mentioned, we currently use pytest
for the tests we
have. To run the tests, simply navigate to the python
directory on
the command line and run:
pytest
and the tests will run. Current testing includes the following:
Compare with data produced by the original Matlab version of the box model and ensure the differences is values is small
Compare the box model results using the default parameters with previously generated data
Acknowledgements
This code was produced under the DARPA AI-assisted Climate Tipping-point Modeling (ACTM) program, and in association with Johns Hopkins University.
1 Gnanadesikan, A., Kelson, R., & Sten, M. (2018). Flux Correction and Overturning Stability: Insights from a Dynamical Box Model, Journal of Climate, 31(22), 9335-9350. Retrieved Mar 30, 2022 from