From 67d5ea0645a48aadd2017d480c2462381a4cc780 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Thu, 10 Sep 2020 15:47:40 -0600 Subject: [PATCH 01/26] Initial docs after quickstart + babelizer logo --- docs/Makefile | 20 +++++++ docs/make.bat | 35 +++++++++++ .../_static/babelizer-logo-lowercase.png | Bin 0 -> 7707 bytes docs/source/conf.py | 55 ++++++++++++++++++ docs/source/index.rst | 23 ++++++++ 5 files changed, 133 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/make.bat create mode 100644 docs/source/_static/babelizer-logo-lowercase.png create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..d0c3cbf1 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 00000000..6247f7e2 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/source/_static/babelizer-logo-lowercase.png b/docs/source/_static/babelizer-logo-lowercase.png new file mode 100644 index 0000000000000000000000000000000000000000..4dae1339ba826254a3579835913b6ec1fa6e280f GIT binary patch literal 7707 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 Date: Thu, 10 Sep 2020 15:49:54 -0600 Subject: [PATCH 02/26] Add intro and links --- docs/source/index.rst | 44 +++++++++++++++++++++++++++++++++++-------- 1 file changed, 36 insertions(+), 8 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 23eedd48..30c24ca7 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -6,18 +6,46 @@ .. title:: babelizer -Welcome to babelizer's documentation! -===================================== + +The *babelizer* is an open source Python utility, +developed by the `Community Surface Dynamics Modeling System`_ (CSDMS), +for wrapping models that expose a `Basic Model Interface`_ (BMI) +so they can imported as Python packages. + +Supported languages include: + +* C +* C++ +* Fortran + +Within Python, models, regardless of their core language, +appear as classes that expose a BMI. +Users are then able to run models interactively +through the Python command line or a Jupyter Notebook, +or programmatically through Python scripts. +They case also use Python-based BMI tools such as +the bmi-tester, pymt, or Landlab. + + +User Guide +========== .. toctree:: :maxdepth: 2 - :caption: Contents: +Help +==== + +Adding a BMI to a model can be a daunting task. +If you'd like assistance, CSDMS can help. +Depending on your need, we can provide advice or consulting services. +Feel free to contact us through the `CSDMS Help Desk`_. + -Indices and tables -================== +.. + Links -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` +.. _Community Surface Dynamics Modeling System: https://csdms.colorado.edu +.. _Basic Model Interface: https://github.com/csdms/bmi +.. _CSDMS Help Desk: https://github.com/csdms/help-desk From b8275914ad0826651a4b051fff6df1544a8b457b Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Thu, 10 Sep 2020 15:52:41 -0600 Subject: [PATCH 03/26] Fill out sidebar Match the style of the pymt docs, https://pymt.readthedocs.io. --- .../source/_static/powered-by-logo-header.png | Bin 0 -> 15416 bytes docs/source/_templates/links.html | 7 ++++++ docs/source/_templates/sidebarintro.html | 6 +++++ docs/source/conf.py | 22 +++++++++++++++++- 4 files changed, 34 insertions(+), 1 deletion(-) create mode 100644 docs/source/_static/powered-by-logo-header.png create mode 100644 docs/source/_templates/links.html create mode 100644 docs/source/_templates/sidebarintro.html diff --git a/docs/source/_static/powered-by-logo-header.png b/docs/source/_static/powered-by-logo-header.png new file mode 100644 index 0000000000000000000000000000000000000000..46c82d07f6e2f212423e1512dd8462b623ffd7b8 GIT binary patch literal 15416 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�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 literal 0 HcmV?d00001 diff --git a/docs/source/_templates/links.html b/docs/source/_templates/links.html new file mode 100644 index 00000000..dfe571d3 --- /dev/null +++ b/docs/source/_templates/links.html @@ -0,0 +1,7 @@ +

Useful Links

+ + diff --git a/docs/source/_templates/sidebarintro.html b/docs/source/_templates/sidebarintro.html new file mode 100644 index 00000000..cec7240a --- /dev/null +++ b/docs/source/_templates/sidebarintro.html @@ -0,0 +1,6 @@ +

About babelizer

+

+ The babelizer wraps libraries + that expose a Basic Model Interface (BMI) + so they can imported as Python packages. +

diff --git a/docs/source/conf.py b/docs/source/conf.py index cb9047f7..35e2652a 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -52,4 +52,24 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] \ No newline at end of file +html_static_path = ['_static'] + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +html_logo = "_static/powered-by-logo-header.png" + +# Custom sidebar templates, maps document names to template names. +html_sidebars = { + "index": [ + "sidebarintro.html", + "links.html", + "sourcelink.html", + "searchbox.html", + ], + "**": [ + "sidebarintro.html", + "links.html", + "sourcelink.html", + "searchbox.html", + ] +} From 311c9fae2274c0eecb902c7ef12350df66b0368e Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Thu, 10 Sep 2020 16:02:03 -0600 Subject: [PATCH 04/26] Add links for bmi-tester, pymt, and Landlab --- docs/source/index.rst | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 30c24ca7..818c6c1b 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -18,13 +18,13 @@ Supported languages include: * C++ * Fortran -Within Python, models, regardless of their core language, +Within Python, these models, regardless of their core language, appear as classes that expose a BMI. Users are then able to run models interactively -through the Python command line or a Jupyter Notebook, -or programmatically through Python scripts. -They case also use Python-based BMI tools such as -the bmi-tester, pymt, or Landlab. +through the Python command line or Jupyter Notebook, +and programmatically through Python scripts; +they can also use Python-based BMI tools such as +the `bmi-tester`_, `pymt`_, and `Landlab`_. User Guide @@ -48,4 +48,7 @@ Feel free to contact us through the `CSDMS Help Desk`_. .. _Community Surface Dynamics Modeling System: https://csdms.colorado.edu .. _Basic Model Interface: https://github.com/csdms/bmi +.. _bmi-tester: https://github.com/csdms/bmi-tester +.. _pymt: https://pymt.readthedocs.io/ +.. _Landlab: https://landlab.github.io/ .. _CSDMS Help Desk: https://github.com/csdms/help-desk From e341a4b9c21acbc79f4e3b35568c8f2260851ff9 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Thu, 10 Sep 2020 16:20:36 -0600 Subject: [PATCH 05/26] Stub out sections for content --- docs/source/commands.rst | 2 + docs/source/example.rst | 2 + docs/source/glossary.rst | 119 +++++++++++++++++++++++++++++++++++ docs/source/index.rst | 8 ++- docs/source/input_file.rst | 2 + docs/source/installation.rst | 2 + 6 files changed, 134 insertions(+), 1 deletion(-) create mode 100644 docs/source/commands.rst create mode 100644 docs/source/example.rst create mode 100644 docs/source/glossary.rst create mode 100644 docs/source/input_file.rst create mode 100644 docs/source/installation.rst diff --git a/docs/source/commands.rst b/docs/source/commands.rst new file mode 100644 index 00000000..675c188b --- /dev/null +++ b/docs/source/commands.rst @@ -0,0 +1,2 @@ +Commands +======== diff --git a/docs/source/example.rst b/docs/source/example.rst new file mode 100644 index 00000000..de61f576 --- /dev/null +++ b/docs/source/example.rst @@ -0,0 +1,2 @@ +Example +======= diff --git a/docs/source/glossary.rst b/docs/source/glossary.rst new file mode 100644 index 00000000..a8a0ffec --- /dev/null +++ b/docs/source/glossary.rst @@ -0,0 +1,119 @@ +Glossary +======== + +A glossary of terms used with the *babelizer*. + + +.. glossary:: + + $ + + The default shell prompt. + + Anaconda + + A Python distribution that includes libraries for scientific + computing and a package manager. See + https://www.anaconda.com/distribution for more information. + + Basic Model Interface + + A set a functions that are used to interact with and control a + model. See https://bmi.readthedocs.io for more information. + + BMI + + See :term:`Basic Model Interface`. + + Community Surface Dynamics Modeling System + + CSDMS is an NSF-funded program that seeks to transform the + science and practice of earth-surface dynamics modeling. For + more information, visit https://csdms.colorado.edu. + + class + + A program that acts as a template for creating + :term:`objects`. + + conda + + The package manager for :term:`Anaconda`. Also an informal name + for an Anaconda installation. + + conda-forge + + A collection of community-built packages distributed by + :term:`Anaconda`. See https://conda-forge.org. + + conda environment + + A :term:`conda` sub-installation that isolates a group of + packages from the main conda installation. + + configuration file + + A file that contains information, including initial values of + parameters, for setting up a :term:`model`. + + coupling + + See :term:`model coupling`. + + CSDMS + + See :term:`Community Surface Dynamics Modeling System`. + + data + + Information held by an :term:`object`. + + import + + The process of bringing code from a Python :term:`module` into + another module or into an interactive Python session. + + instance + + See :term:`object`. + + method + + Programs that act upon the :term:`data` of an :term:`object`. + + model + + A computer program that attempts to describe a physical process + with mathematical relationships that evolve over time and are + solved numerically. For more information, see, for example, + https://en.wikipedia.org/wiki/Numerical_modeling_(geology). + + model configuration file + + A file, usually in a text-based format, that lists the tunable + parameters of a model and supplies their initial values. + + model coupling + + Models are *coupled* when they exchange inputs and outputs, + often at the resolution of individual time steps. *One-way + coupling* occurs when the outputs from one model are used as + inputs to another model. *Two-way coupling* is when outputs from + one model are used as inputs for another model, which in turn + supplies its outputs to the first model as inputs, producing a + feedback. + + module + + A file (with the ``.py`` extension) that contains Python code. + + NumPy + + A Python library that provides arrays. Outputs from *pymt* are + NumPy arrays. See also http://www.numpy.org. + + object + + A variable that is a concrete example of a + :term:`class`. Objects have :term:`data` and + :term:`methods` that act upon those data. diff --git a/docs/source/index.rst b/docs/source/index.rst index 818c6c1b..f92d2abd 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -31,7 +31,13 @@ User Guide ========== .. toctree:: - :maxdepth: 2 + :maxdepth: 1 + + installation + commands + input_file + example + glossary Help diff --git a/docs/source/input_file.rst b/docs/source/input_file.rst new file mode 100644 index 00000000..eb0fecae --- /dev/null +++ b/docs/source/input_file.rst @@ -0,0 +1,2 @@ +Input file +========== diff --git a/docs/source/installation.rst b/docs/source/installation.rst new file mode 100644 index 00000000..11e44375 --- /dev/null +++ b/docs/source/installation.rst @@ -0,0 +1,2 @@ +Installation +============ From 33facc16d38321691a4e0323fe9dddf37d00b4fa Mon Sep 17 00:00:00 2001 From: mcflugen Date: Thu, 10 Sep 2020 22:04:34 -0600 Subject: [PATCH 06/26] add napoleon and autodoc extensions --- docs/source/conf.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 35e2652a..22a47675 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -30,8 +30,7 @@ # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = [ -] +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] From 8d7c0a39054b44a2d957b752781c064dac5357a9 Mon Sep 17 00:00:00 2001 From: mcflugen Date: Thu, 10 Sep 2020 22:04:55 -0600 Subject: [PATCH 07/26] add lint and docs stages --- .travis.yml | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/.travis.yml b/.travis.yml index 0848b28e..1144bfb1 100644 --- a/.travis.yml +++ b/.travis.yml @@ -6,6 +6,23 @@ env: matrix: - PYTHON="3.8" sudo: false + +jobs: + include: + - stage: lint + os: linux + script: + - pip install flake8 + - make lint + + - stage: docs + os: linux + install: + - pip install -r requirements-docs.txt + - pip install -e . + script: + - make -C docs clean html + before_install: - | if [[ $TRAVIS_OS_NAME == "osx" ]]; then From 5d8b38f06be79561c78cfad786368791ea02c6c4 Mon Sep 17 00:00:00 2001 From: mcflugen Date: Thu, 10 Sep 2020 22:07:21 -0600 Subject: [PATCH 08/26] add readthedocs config file --- .readthedocs.yaml | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 .readthedocs.yaml diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..f8dd6ae2 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,21 @@ +version: 2 + +sphinx: + builder: html + configuration: docs/source/conf.py + fail_on_warning: false + +formats: + - htmlzip + +python: + version: 3.8 + install: + - requirements: requirements-docs.txt + - requirements: requirements.txt + - method: pip + path: . + system_packages: false + +build: + image: latest From 7e0dd34f7661112510345ce6a15a595b0d53369e Mon Sep 17 00:00:00 2001 From: mcflugen Date: Thu, 10 Sep 2020 22:08:57 -0600 Subject: [PATCH 09/26] add requirements file for building docs --- requirements-docs.txt | 1 + 1 file changed, 1 insertion(+) create mode 100644 requirements-docs.txt diff --git a/requirements-docs.txt b/requirements-docs.txt new file mode 100644 index 00000000..2236f915 --- /dev/null +++ b/requirements-docs.txt @@ -0,0 +1 @@ +sphinx>=1.5.1, <3 From 9571137e41cb261af7a48ca077f3c5c320f1910b Mon Sep 17 00:00:00 2001 From: mcflugen Date: Thu, 10 Sep 2020 22:10:27 -0600 Subject: [PATCH 10/26] remove lint --- setup.py | 2 +- tests/test_c.py | 2 -- 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/setup.py b/setup.py index 1ea00f10..17b38cd5 100644 --- a/setup.py +++ b/setup.py @@ -35,5 +35,5 @@ def read(filename): install_requires=open("requirements.txt", "r").read().splitlines(), packages=find_packages(), include_package_data=True, - entry_points={"console_scripts": ["babelize=babelizer.cli:babelize",],}, + entry_points={"console_scripts": ["babelize=babelizer.cli:babelize"]}, ) diff --git a/tests/test_c.py b/tests/test_c.py index de8ade26..20374fa2 100644 --- a/tests/test_c.py +++ b/tests/test_c.py @@ -3,9 +3,7 @@ import pathlib import shutil import subprocess -import sys -import pytest from click.testing import CliRunner from babelizer.cli import babelize From 90386cf5d7dd7baa1a74e8e69267da5dcba30d6a Mon Sep 17 00:00:00 2001 From: mcflugen Date: Thu, 10 Sep 2020 22:12:30 -0600 Subject: [PATCH 11/26] set master_doc to index (default is contents) --- docs/source/conf.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/source/conf.py b/docs/source/conf.py index 22a47675..f8eb2330 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -15,6 +15,9 @@ # sys.path.insert(0, os.path.abspath('.')) +# The master toctree document. +master_doc = 'index' + # -- Project information ----------------------------------------------------- project = 'babelizer' From 66d6318797a060ae5808dde4f26b180511c80c67 Mon Sep 17 00:00:00 2001 From: mcflugen Date: Thu, 10 Sep 2020 23:01:59 -0600 Subject: [PATCH 12/26] change license to rst format --- LICENSE | 21 --------------------- LICENSE.rst | 26 ++++++++++++++++++++++++++ MANIFEST.in | 2 +- 3 files changed, 27 insertions(+), 22 deletions(-) delete mode 100644 LICENSE create mode 100644 LICENSE.rst diff --git a/LICENSE b/LICENSE deleted file mode 100644 index e3dbc24a..00000000 --- a/LICENSE +++ /dev/null @@ -1,21 +0,0 @@ -MIT License - -Copyright (c) 2018 Community Surface Dynamics Modeling System - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. diff --git a/LICENSE.rst b/LICENSE.rst new file mode 100644 index 00000000..a01c8436 --- /dev/null +++ b/LICENSE.rst @@ -0,0 +1,26 @@ +The MIT License (MIT) +===================== + +Copyright © `2020` `Community Surface Dynamics Modeling System` + +Permission is hereby granted, free of charge, to any person +obtaining a copy of this software and associated documentation +files (the "Software"), to deal in the Software without +restriction, including without limitation the rights to use, +copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the +Software is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +OTHER DEALINGS IN THE SOFTWARE. + diff --git a/MANIFEST.in b/MANIFEST.in index 5044246c..56b671b4 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,4 +1,4 @@ -include LICENSE +include LICENSE.rst include CHANGES.rst include requirements.txt recursive-include babelizer/data * From 53384138fddea01e3a3fd5fde786923c11b3a521 Mon Sep 17 00:00:00 2001 From: mcflugen Date: Thu, 10 Sep 2020 23:24:12 -0600 Subject: [PATCH 13/26] add contributing doc --- CONTRIBUTING.rst | 131 +++++++++++++++++++++++++++++++++++ docs/source/contributing.rst | 1 + 2 files changed, 132 insertions(+) create mode 100644 CONTRIBUTING.rst create mode 100644 docs/source/contributing.rst diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 00000000..09d870ee --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1,131 @@ +.. highlight:: shell + +============ +Contributing +============ + +Contributions are welcome, and they are greatly appreciated! Every little bit +helps, and credit will always be given. + +You can contribute in many ways: + +Types of Contributions +---------------------- + +Report Bugs +~~~~~~~~~~~ + +Report bugs at https://github.com/csdms/babelizer/issues. + +If you are reporting a bug, please include: + +* Your operating system name and version. +* Any details about your local setup that might be helpful in troubleshooting. +* Detailed steps to reproduce the bug. + +Fix Bugs +~~~~~~~~ + +Look through the GitHub issues for bugs. Anything tagged with "bug" and "help +wanted" is open to whoever wants to implement it. + +Implement Features +~~~~~~~~~~~~~~~~~~ + +Look through the GitHub issues for features. Anything tagged with "enhancement" +and "help wanted" is open to whoever wants to implement it. + +Write Documentation +~~~~~~~~~~~~~~~~~~~ + +*babelizer* could always use more documentation, whether as part of the +official *babelizer* docs, in docstrings, or even on the web in blog posts, +articles, and such. + +Submit Feedback +~~~~~~~~~~~~~~~ + +The best way to send feedback is to file an issue at https://github.com/csdms/babelizer/issues. + +If you are proposing a feature: + +* Explain in detail how it would work. +* Keep the scope as narrow as possible, to make it easier to implement. +* Remember that this is a volunteer-driven project, and that contributions + are welcome :) + +Get Started! +------------ + +Ready to contribute? Here's how to set up *babelizer* for local development. + +1. Fork the *babelizer* repo on GitHub. +2. Clone your fork locally:: + + $ git clone git@github.com:your_name_here/babelizer.git + +3. Install your local copy into a conda environment. Assuming you have conda + installed, this is how you set up your fork for local development:: + + $ conda create -n babelizer python=3.8 + $ conda activate babelizer + $ cd babelizer/ + $ conda install --file=requirements.txt + + $ python setup.py develop + +4. Create a branch for local development:: + + $ git checkout -b name-of-your-bugfix-or-feature + + Now you can make your changes locally. + +5. When you're done making changes, check that your changes pass flake8 and the + tests:: + + $ make lint + $ make test + + To get flake8, just conda install it into your environment. + +6. Commit your changes and push your branch to GitHub:: + + $ git add . + $ git commit -m "Your detailed description of your changes." + $ git push origin name-of-your-bugfix-or-feature + +7. Submit a pull request through the GitHub website. + +Pull Request Guidelines +----------------------- + +Before you submit a pull request, check that it meets these guidelines: + +1. The pull request should include tests. +2. If the pull request adds functionality, the docs should be updated. Put + your new functionality into a function with a docstring, and add the + feature to the list in README.rst. +3. The pull request need only work with Python >= 3.8. Check + https://travis-ci.org/csdms/babelizer/pull_requests + and make sure that the tests pass. + +Deploying +--------- + +A reminder for the maintainers on how to deploy. To make a new release, +you will need to have [zest.releaser](https://zestreleaser.readthedocs.io/en/latest/) +installed, which can be installed with *pip*, + +.. code:: bash + + $ pip install zest.releaser[recommended] + +Make sure all your changes are committed (including an entry in CHANGES.rst). +Then run, + +.. code:: bash + + $ fullrelease + +This will create a new tag and alert the *babelizer* feedstock on +*conda-forge* that there is a new release. diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst new file mode 100644 index 00000000..ac7b6bcf --- /dev/null +++ b/docs/source/contributing.rst @@ -0,0 +1 @@ +.. include:: ../../CONTRIBUTING.rst From 4a7a3b7b5ede209a486cccc1231634e9ddc5d683 Mon Sep 17 00:00:00 2001 From: mcflugen Date: Thu, 10 Sep 2020 23:25:00 -0600 Subject: [PATCH 14/26] add misc sections to docs --- docs/source/index.rst | 36 +++++++++++++++++++++++++++++++----- 1 file changed, 31 insertions(+), 5 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index f92d2abd..5a4635bf 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -31,14 +31,28 @@ User Guide ========== .. toctree:: - :maxdepth: 1 + :maxdepth: 2 - installation - commands - input_file - example + readme glossary +.. installation +.. commands +.. input_file +.. example + + +API Reference +------------- + +If you are looking for information on a specific function, class, or +method, this part of the documentation is for you. + +.. toctree:: + :maxdepth: 2 + + api/index + Help ==== @@ -49,6 +63,18 @@ Depending on your need, we can provide advice or consulting services. Feel free to contact us through the `CSDMS Help Desk`_. +Miscellaneous Pages +------------------- + +.. toctree:: + :maxdepth: 2 + + authors + changelog + contributing + license + + .. Links From 16c28b0722ef936437c26c5525e2d4655080f67c Mon Sep 17 00:00:00 2001 From: mcflugen Date: Thu, 10 Sep 2020 23:30:37 -0600 Subject: [PATCH 15/26] install with conda (babelizer isn't on pypi yet) --- README.rst | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/README.rst b/README.rst index 0b2addcb..609353a5 100644 --- a/README.rst +++ b/README.rst @@ -30,7 +30,7 @@ Supported languages: Requirements ************ -The *babelizer* is Python 3 only. +The *babelizer* requires Python >=3.8. Apart from Python, the *babelzer* has a number of other requirements, all of which @@ -52,20 +52,19 @@ Installation To install the *babelizer*, first create a new environment in which *babelizer* will be installed. This, although not necessary, will isolate the installation so that there won't be conflicts with your -base *Python* installation. This can be done with *conda* as:: +base *Python* installation. This can be done with *conda* as, - $ conda create -n babelizer python=3 - $ conda activate babelizer +.. code:: bash + + $ conda create -n babelizer python=3 + $ conda activate babelizer Stable Release ============== -The *babelizer*, and its dependencies, can be installed either with *pip* -or *conda*. Using *pip*:: +The *babelizer*, and its dependencies, is best installed with *conda*, - $ pip install babelizer - -Using *conda*:: +.. code:: bash $ conda install babelizer -c conda-forge @@ -257,7 +256,11 @@ For example the above *babel.toml* can be generated with the following, .. code:: bash - $ babelize generate babel.toml --summary="PyMT plugin for hydrotrend" --entry-point=Hydrotrend=bmi_hydrotrend:register_bmi_hydrotrend --name=hydrotrend --requirement=hydrotrend + $ babelize generate babel.toml \ + --summary="PyMT plugin for hydrotrend" \ + --entry-point=Hydrotrend=bmi_hydrotrend:register_bmi_hydrotrend \ + --name=hydrotrend \ + --requirement=hydrotrend ******** Examples From b150a45cf6e0c81a1e46221536cdd8fb048dbdfd Mon Sep 17 00:00:00 2001 From: mcflugen Date: Thu, 10 Sep 2020 23:31:10 -0600 Subject: [PATCH 16/26] add sections that include top-level rst files --- docs/source/api/index.rst | 7 +++++++ docs/source/authors.rst | 1 + docs/source/changelog.rst | 1 + docs/source/license.rst | 5 +++++ docs/source/readme.rst | 1 + 5 files changed, 15 insertions(+) create mode 100644 docs/source/api/index.rst create mode 100644 docs/source/authors.rst create mode 100644 docs/source/changelog.rst create mode 100644 docs/source/license.rst create mode 100644 docs/source/readme.rst diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst new file mode 100644 index 00000000..5fbee2fd --- /dev/null +++ b/docs/source/api/index.rst @@ -0,0 +1,7 @@ +Developer Documentation +----------------------- + +.. toctree:: + :maxdepth: 2 + + modules diff --git a/docs/source/authors.rst b/docs/source/authors.rst new file mode 100644 index 00000000..e2f0e1c0 --- /dev/null +++ b/docs/source/authors.rst @@ -0,0 +1 @@ +.. include:: ../../CREDITS.rst diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst new file mode 100644 index 00000000..d76c92b6 --- /dev/null +++ b/docs/source/changelog.rst @@ -0,0 +1 @@ +.. include:: ../../CHANGES.rst diff --git a/docs/source/license.rst b/docs/source/license.rst new file mode 100644 index 00000000..b187ecc8 --- /dev/null +++ b/docs/source/license.rst @@ -0,0 +1,5 @@ +======= +License +======= + +.. include:: ../../LICENSE.rst diff --git a/docs/source/readme.rst b/docs/source/readme.rst new file mode 100644 index 00000000..a6210d3d --- /dev/null +++ b/docs/source/readme.rst @@ -0,0 +1 @@ +.. include:: ../../README.rst From 0ef0754c96f5d0b4cd743c7ad6847fd508cfbdee Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Fri, 11 Sep 2020 13:57:39 -0600 Subject: [PATCH 17/26] Remove files for unused sections --- docs/source/commands.rst | 2 -- docs/source/index.rst | 8 ++------ docs/source/input_file.rst | 2 -- docs/source/installation.rst | 2 -- 4 files changed, 2 insertions(+), 12 deletions(-) delete mode 100644 docs/source/commands.rst delete mode 100644 docs/source/input_file.rst delete mode 100644 docs/source/installation.rst diff --git a/docs/source/commands.rst b/docs/source/commands.rst deleted file mode 100644 index 675c188b..00000000 --- a/docs/source/commands.rst +++ /dev/null @@ -1,2 +0,0 @@ -Commands -======== diff --git a/docs/source/index.rst b/docs/source/index.rst index 5a4635bf..ea9768b1 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -34,13 +34,9 @@ User Guide :maxdepth: 2 readme + example glossary -.. installation -.. commands -.. input_file -.. example - API Reference ------------- @@ -57,7 +53,7 @@ method, this part of the documentation is for you. Help ==== -Adding a BMI to a model can be a daunting task. +Adding a BMI to a model and babelizing it can be a daunting task. If you'd like assistance, CSDMS can help. Depending on your need, we can provide advice or consulting services. Feel free to contact us through the `CSDMS Help Desk`_. diff --git a/docs/source/input_file.rst b/docs/source/input_file.rst deleted file mode 100644 index eb0fecae..00000000 --- a/docs/source/input_file.rst +++ /dev/null @@ -1,2 +0,0 @@ -Input file -========== diff --git a/docs/source/installation.rst b/docs/source/installation.rst deleted file mode 100644 index 11e44375..00000000 --- a/docs/source/installation.rst +++ /dev/null @@ -1,2 +0,0 @@ -Installation -============ From 8afd80a578ef0f1cb05b2f56e1224895f57d6124 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Fri, 11 Sep 2020 13:58:37 -0600 Subject: [PATCH 18/26] Fix link from logo image --- docs/source/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index ea9768b1..cd5c449b 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -2,7 +2,7 @@ :align: center :scale: 85% :alt: babelizer - :target: https://bmi.readthedocs.io/ + :target: https://babelizer.readthedocs.io/ .. title:: babelizer From 1003ba51124a0b7a9bbd4e6e565409a5c4f6bc61 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Tue, 15 Sep 2020 11:50:29 -0600 Subject: [PATCH 19/26] Outline example of wrapping a C model Also started the first two sections of the example. --- README.rst | 13 +++- docs/source/environment.yml | 11 ++++ docs/source/example.rst | 127 +++++++++++++++++++++++++++++++++++- docs/source/glossary.rst | 13 ++-- 4 files changed, 152 insertions(+), 12 deletions(-) create mode 100644 docs/source/environment.yml diff --git a/README.rst b/README.rst index 609353a5..49bf664e 100644 --- a/README.rst +++ b/README.rst @@ -262,9 +262,9 @@ For example the above *babel.toml* can be generated with the following, --name=hydrotrend \ --requirement=hydrotrend -******** -Examples -******** +*** +Use +*** Generate Python bindings for a library that implements a BMI, sending output to the current directory @@ -278,3 +278,10 @@ Update an existing repository .. code:: bash $ babelize update + +For a complete example of using the *babelizer* +to wrap a C library exposing a BMI, +see the User Guide of the `documentation`_. + + +.. _documentation: https://babelizer.readthedocs.io/ diff --git a/docs/source/environment.yml b/docs/source/environment.yml new file mode 100644 index 00000000..e8851d0a --- /dev/null +++ b/docs/source/environment.yml @@ -0,0 +1,11 @@ +# A conda environment file for the babelizer example +name: wrap +channels: + - conda-forge +dependencies: +- python=3 +- cmake +- pkg-config +- c-compiler +- bmi-c +- babelizer diff --git a/docs/source/example.rst b/docs/source/example.rst index de61f576..4eb09634 100644 --- a/docs/source/example.rst +++ b/docs/source/example.rst @@ -1,2 +1,125 @@ -Example -======= +Example: Wrapping a C model +=========================== + +In this example, we'll use the *babelizer* +to wrap the model *heat* from the `bmi-example-c`_ repository, +allowing it to run in Python. +The model and its BMI are written in C. +To simplify package management in the example, +we'll use :term:`conda`. +We'll also use :term:`git` to obtain the model source code. + +Starting from the model source code, +here are the steps we'll take to wrap the model: + +#. Create a :term:`conda environment` that includes packages to compile the + model and wrap it with the *babelizer* +#. Clone the `bmi-example-c`_ repository from GitHub and build the + *heat* model from source +#. Create a *babelizer* input file for the *heat* model +#. Run the *babelizer* to wrap the model in Python +#. Run the *heat* model in Python through *pymt* + + +Set up a conda environment +-------------------------- + +Start by setting up a :term:`conda environment` +where we can build and wrap the model. +We'll need a compiler toolchain to build and install the model, +as well as the *babelizer*. +The necessary packages are listed in the conda environment file +:download:`environment.yml`: + +.. include:: environment.yml + :literal: + +Download this file and create the new environment with: + +.. code:: bash + + conda env create --file=environment.yml + +When this command completes, +activate the *wrap* environment: + +.. code:: bash + + conda activate wrap + +The *wrap* environment now contains all the dependencies needed +to build, install, and wrap the *heat* model. + + +Build the *heat* model from source +---------------------------------- + +Clone the `bmi-example-c`_ repository from GitHub: + +.. code:: bash + + git clone https://github.com/csdms/bmi-example-c + +The repository `README`_ contains general instructions for building and installing +this package on Linux, macOS, and Windows. +We'll augment those instructions +with the note that we're installing into the *wrap* conda environment, +so the ``CONDA_PREFIX`` environment variable +should be used to specify the install path. + +Build on Linux and macOS +........................ + +On Linux and macOS, +use these commands to build and install the *heat* model: + +.. code:: bash + + cd bmi-example-c + mkdir _build && cd _build + cmake .. -DCMAKE_INSTALL_PREFIX=$CONDA_PREFIX + make + make install + +Verify the install by testing for the existence of the header +of the library containing the compiled *heat* model: + +.. code:: bash + + test -f $CONDA_PREFIX/include/bmi_heat.h + +Build on Windows +................ + +Building on Windows requires +Microsoft Visual Studio 2017 or Microsoft Build Tools for Visual Studio 2017. +To build and install the *heat* model, +the following commands must be run in a `Developer Command Prompt`_: + +.. code:: + + cd bmi-example-c + mkdir _build && cd _build + cmake .. ^ + -G "NMake Makefiles" ^ + -DCMAKE_INSTALL_PREFIX=%CONDA_PREFIX% ^ + -DCMAKE_BUILD_TYPE=Release + cmake --build . --target install --config Release + +Verify the install by testing for the existence of the header +of the library containing the compiled *heat* model: + +.. code:: + + if not exist %LIBRARY_INC%\\bmi_heat.h exit 1 + +Create the *babelizer* input file +--------------------------------- + + +.. + Links + +.. _bmi-example-c: https://github.com/csdms/bmi-example-c +.. _README: https://github.com/csdms/bmi-example-c/blob/master/README.md +.. _Developer Command Prompt: https://docs.microsoft.com/en-us/dotnet/framework/tools/developer-command-prompt-for-vs diff --git a/docs/source/glossary.rst b/docs/source/glossary.rst index a8a0ffec..f2f15391 100644 --- a/docs/source/glossary.rst +++ b/docs/source/glossary.rst @@ -53,8 +53,8 @@ A glossary of terms used with the *babelizer*. configuration file - A file that contains information, including initial values of - parameters, for setting up a :term:`model`. + A file, usually in a text-based format, that lists the tunable + parameters of a :term:`model` and supplies their initial values. coupling @@ -68,6 +68,10 @@ A glossary of terms used with the *babelizer*. Information held by an :term:`object`. + git + + Version control software. + import The process of bringing code from a Python :term:`module` into @@ -88,11 +92,6 @@ A glossary of terms used with the *babelizer*. solved numerically. For more information, see, for example, https://en.wikipedia.org/wiki/Numerical_modeling_(geology). - model configuration file - - A file, usually in a text-based format, that lists the tunable - parameters of a model and supplies their initial values. - model coupling Models are *coupled* when they exchange inputs and outputs, From 02c4d7fe478802206e204632b8ea1a8cad69d87b Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Tue, 15 Sep 2020 18:42:56 -0600 Subject: [PATCH 20/26] Draft sections for babelize generate and babelize init They still need a little polish, but they work. --- docs/source/babel_heatc.toml | 23 ++++++ docs/source/example.rst | 156 +++++++++++++++++++++++++++++------ 2 files changed, 155 insertions(+), 24 deletions(-) create mode 100644 docs/source/babel_heatc.toml diff --git a/docs/source/babel_heatc.toml b/docs/source/babel_heatc.toml new file mode 100644 index 00000000..c5ff2e55 --- /dev/null +++ b/docs/source/babel_heatc.toml @@ -0,0 +1,23 @@ +[library] +language = "c" +entry_point = ["HeatModel=bmiheatc:register_bmi_heat"] + +[build] +undef_macros = [] +define_macros = [] +libraries = [] +library_dirs = [] +include_dirs = [] +extra_compile_args = [] + +[plugin] +name = "heatc" +requirements = [""] + +[info] +plugin_author = "csdms" +plugin_author_email = "csdms@colorado.edu" +github_username = "pymt-lab" +plugin_license = "MIT" +summary = "PyMT plugin for heat model" + diff --git a/docs/source/example.rst b/docs/source/example.rst index 4eb09634..2d69bf13 100644 --- a/docs/source/example.rst +++ b/docs/source/example.rst @@ -2,17 +2,18 @@ Example: Wrapping a C model =========================== In this example, we'll use the *babelizer* -to wrap the model *heat* from the `bmi-example-c`_ repository, -allowing it to run in Python. +to wrap the *heat* model from the `bmi-example-c`_ repository, +allowing it to be run in Python. The model and its BMI are written in C. To simplify package management in the example, we'll use :term:`conda`. We'll also use :term:`git` to obtain the model source code. -Starting from the model source code, -here are the steps we'll take to wrap the model: +This is a somewhat long example. +To break it up, +here are the steps we'll take: -#. Create a :term:`conda environment` that includes packages to compile the +#. Create a :term:`conda environment` that includes software to compile the model and wrap it with the *babelizer* #. Clone the `bmi-example-c`_ repository from GitHub and build the *heat* model from source @@ -20,6 +21,14 @@ here are the steps we'll take to wrap the model: #. Run the *babelizer* to wrap the model in Python #. Run the *heat* model in Python through *pymt* +Before we begin, +create a directory to hold the work we'll do: + +.. code:: bash + + $ mkdir build + $ cd build + Set up a conda environment -------------------------- @@ -34,18 +43,19 @@ The necessary packages are listed in the conda environment file .. include:: environment.yml :literal: -Download this file and create the new environment with: +Download :download:`this file ` +and create the new environment with: .. code:: bash - conda env create --file=environment.yml + $ conda env create --file=environment.yml When this command completes, activate the *wrap* environment: .. code:: bash - conda activate wrap + $ conda activate wrap The *wrap* environment now contains all the dependencies needed to build, install, and wrap the *heat* model. @@ -58,7 +68,7 @@ Clone the `bmi-example-c`_ repository from GitHub: .. code:: bash - git clone https://github.com/csdms/bmi-example-c + $ git clone https://github.com/csdms/bmi-example-c The repository `README`_ contains general instructions for building and installing this package on Linux, macOS, and Windows. @@ -67,29 +77,29 @@ with the note that we're installing into the *wrap* conda environment, so the ``CONDA_PREFIX`` environment variable should be used to specify the install path. -Build on Linux and macOS -........................ +Linux and macOS +............... On Linux and macOS, use these commands to build and install the *heat* model: .. code:: bash - cd bmi-example-c - mkdir _build && cd _build - cmake .. -DCMAKE_INSTALL_PREFIX=$CONDA_PREFIX - make - make install + $ cd bmi-example-c + $ mkdir _build && cd _build + $ cmake .. -DCMAKE_INSTALL_PREFIX=$CONDA_PREFIX + $ make + $ make install Verify the install by testing for the existence of the header of the library containing the compiled *heat* model: .. code:: bash - test -f $CONDA_PREFIX/include/bmi_heat.h + $ test -f $CONDA_PREFIX/include/bmi_heat.h -Build on Windows -................ +Windows +....... Building on Windows requires Microsoft Visual Studio 2017 or Microsoft Build Tools for Visual Studio 2017. @@ -98,24 +108,122 @@ the following commands must be run in a `Developer Command Prompt`_: .. code:: - cd bmi-example-c - mkdir _build && cd _build - cmake .. ^ + > cd bmi-example-c + > mkdir _build && cd _build + > cmake .. ^ -G "NMake Makefiles" ^ -DCMAKE_INSTALL_PREFIX=%CONDA_PREFIX% ^ -DCMAKE_BUILD_TYPE=Release - cmake --build . --target install --config Release + > cmake --build . --target install --config Release Verify the install by testing for the existence of the header of the library containing the compiled *heat* model: .. code:: - if not exist %LIBRARY_INC%\\bmi_heat.h exit 1 + > if not exist %LIBRARY_INC%\\bmi_heat.h exit 1 Create the *babelizer* input file --------------------------------- +The *babelizer* input file provides information to the *babelizer* +about the model to be wrapped. +The input file is created with the ``babelize generate`` subcommand. + +Return to our initial ``build`` directory and call ``babelize generate`` with: + +.. code:: bash + + $ cd ~/build + $ babelize generate babel_heatc.toml \ + --language=c \ + --summary="PyMT plugin for heat model" \ + --entry-point=HeatModel=bmiheatc:register_bmi_heat \ + --name=heatc \ + --requirement="" + +In this call, +the *babelizer* will also interactively prompt for author name, author email, +GitHub username, and license. +These can be optionally be filled in, or the defaults can be used. + +The resulting file, ``babel_heatc.toml``, +will look something like this: + +.. include:: babel_heatc.toml + :literal: + +For more information on the entries and sections of the *babelizer* input file, +see `Input file <./readme.html#input-file>`_. + + +Wrap the model with the *babelizer* +----------------------------------- + +Generate Python bindings for the model with the ``babelize init`` subcommand: + +.. code:: bash + + $ babelize init babel_heatc.toml . + +The results are placed in a new directory, ``pymt_heatc``, +under the current directory. + +.. code:: bash + + $ ls -aF pymt_heatc + ./ MANIFEST.in recipe/ + ../ Makefile requirements-library.txt + .git/ README.rst requirements-testing.txt + .gitignore babel.toml requirements.txt + .travis.yml docs/ setup.cfg + CHANGES.rst meta/ setup.py + CREDITS.rst pymt_heatc/ + LICENSE pyproject.toml + +Before we can build the Python bindings, +we must ensure that dependencies required by the toolchain, +as well as any required by the model, +as specified in the *babelizer* input file (none in this case), +are satisfied. + +Change to the ``pymt_heatc`` directory and install dependencies +into the conda environment: + +.. code:: bash + + $ cd pymt_heatc + $ conda install -c conda-forge --file=requirements.txt --file=requirements-library.txt + + +Build the Python bindings with: + +.. code:: bash + + $ make install + +This command sets off a long list of messages, +at the end of which you'll hopefully see: + +.. code:: bash + + Successfully installed pymt-heatc + +Take a moment to pause and see what we've done. +Start a Python session and try the following commands: + +.. code:: python + + >>> from pymt_heatc import HeatModel + >>> m = HeatModel() + >>> print(m.get_component_name()) + The 2D Heat Equation + +We've imported the *heat* model, +written in C, +into Python! + +There are still a few steps remaining... .. Links From 7fd1bb915bd0f1e1afb0923b67f435f472926f52 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Wed, 16 Sep 2020 12:04:02 -0600 Subject: [PATCH 21/26] Add content from sphinx-apidoc --- docs/source/api/babelizer.rst | 61 +++++++++++++++++++++++++++++++++++ docs/source/api/modules.rst | 7 ++++ 2 files changed, 68 insertions(+) create mode 100644 docs/source/api/babelizer.rst create mode 100644 docs/source/api/modules.rst diff --git a/docs/source/api/babelizer.rst b/docs/source/api/babelizer.rst new file mode 100644 index 00000000..3ee00f59 --- /dev/null +++ b/docs/source/api/babelizer.rst @@ -0,0 +1,61 @@ +babelizer package +================= + +Submodules +---------- + +babelizer.cli module +-------------------- + +.. automodule:: babelizer.cli + :members: + :undoc-members: + :show-inheritance: + +babelizer.errors module +----------------------- + +.. automodule:: babelizer.errors + :members: + :undoc-members: + :show-inheritance: + +babelizer.metadata module +------------------------- + +.. automodule:: babelizer.metadata + :members: + :undoc-members: + :show-inheritance: + +babelizer.render module +----------------------- + +.. automodule:: babelizer.render + :members: + :undoc-members: + :show-inheritance: + +babelizer.utils module +---------------------- + +.. automodule:: babelizer.utils + :members: + :undoc-members: + :show-inheritance: + +babelizer.wrap module +--------------------- + +.. automodule:: babelizer.wrap + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: babelizer + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/api/modules.rst b/docs/source/api/modules.rst new file mode 100644 index 00000000..811ffbe8 --- /dev/null +++ b/docs/source/api/modules.rst @@ -0,0 +1,7 @@ +babelizer +========= + +.. toctree:: + :maxdepth: 4 + + babelizer From 2b2d3c79fb10ae162986e65f331b19609d979d8d Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Wed, 16 Sep 2020 16:12:42 -0600 Subject: [PATCH 22/26] Show how to run bmi-tester on the babelized model --- docs/source/example.rst | 51 ++++++++++++++++++++++++++------- docs/source/examples/config.txt | 1 + 2 files changed, 42 insertions(+), 10 deletions(-) create mode 100644 docs/source/examples/config.txt diff --git a/docs/source/example.rst b/docs/source/example.rst index 2d69bf13..10ba15d6 100644 --- a/docs/source/example.rst +++ b/docs/source/example.rst @@ -17,12 +17,12 @@ here are the steps we'll take: model and wrap it with the *babelizer* #. Clone the `bmi-example-c`_ repository from GitHub and build the *heat* model from source -#. Create a *babelizer* input file for the *heat* model -#. Run the *babelizer* to wrap the model in Python -#. Run the *heat* model in Python through *pymt* +#. Create a *babelizer* input file describing the *heat* model +#. Run the *babelizer* to generate Python bindings, then build the bindings +#. Show the *heat* model running in Python through *pymt* Before we begin, -create a directory to hold the work we'll do: +create a directory to hold our work: .. code:: bash @@ -34,8 +34,7 @@ Set up a conda environment -------------------------- Start by setting up a :term:`conda environment` -where we can build and wrap the model. -We'll need a compiler toolchain to build and install the model, +that includes a toolchain to build and install the model, as well as the *babelizer*. The necessary packages are listed in the conda environment file :download:`environment.yml`: @@ -51,7 +50,7 @@ and create the new environment with: $ conda env create --file=environment.yml When this command completes, -activate the *wrap* environment: +activate the environment: .. code:: bash @@ -182,7 +181,7 @@ under the current directory. LICENSE pyproject.toml Before we can build the Python bindings, -we must ensure that dependencies required by the toolchain, +we must ensure that the dependencies required by the toolchain, as well as any required by the model, as specified in the *babelizer* input file (none in this case), are satisfied. @@ -196,7 +195,7 @@ into the conda environment: $ conda install -c conda-forge --file=requirements.txt --file=requirements-library.txt -Build the Python bindings with: +Now build the Python bindings with: .. code:: bash @@ -223,7 +222,37 @@ We've imported the *heat* model, written in C, into Python! -There are still a few steps remaining... +At this point, +it's a good idea to run the *bmi-tester* (`GitHub repo `_) +over the model. +The *bmi-tester* exercises each BMI method exposed through Python, +ensuring it works correctly. + +Install *bmi-tester* with: + +.. code:: bash + + $ conda install -c conda-forge bmi-tester + +Before running the *bmi-tester*, one last piece is needed. +Like all models equipped with a BMI, +*heat* uses a :term:`configuration file` to specify initial parameter values. +Download the file :download:`config.txt ` for use here. + +Run the *bmi-tester* with: + +.. code:: bash + + $ bmi-test pymt_heatc:HeatModel --config-file=config.txt --root-dir=. -vvv + +This command sets off a long list of messages, +ending with + +.. code:: bash + + 🎉 All tests passed! + +if everything has been built correctly. .. Links @@ -231,3 +260,5 @@ There are still a few steps remaining... .. _bmi-example-c: https://github.com/csdms/bmi-example-c .. _README: https://github.com/csdms/bmi-example-c/blob/master/README.md .. _Developer Command Prompt: https://docs.microsoft.com/en-us/dotnet/framework/tools/developer-command-prompt-for-vs +.. _bmi-tester: https://github.com/csdms/bmi-tester +.. _Python Modeling Tool: https://pymt.readthedocs.io diff --git a/docs/source/examples/config.txt b/docs/source/examples/config.txt new file mode 100644 index 00000000..fe07de38 --- /dev/null +++ b/docs/source/examples/config.txt @@ -0,0 +1 @@ +1.5, 8.0, 6, 5 From b30fd2c46b34d298b9c3533ba5218397e4483db2 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Wed, 16 Sep 2020 18:29:04 -0600 Subject: [PATCH 23/26] Include metadata files for the heatc model --- docs/source/examples/heat.txt | 1 + docs/source/examples/info.yaml | 8 ++++++ docs/source/examples/parameters.yaml | 42 ++++++++++++++++++++++++++++ docs/source/examples/run.yaml | 1 + 4 files changed, 52 insertions(+) create mode 100644 docs/source/examples/heat.txt create mode 100644 docs/source/examples/info.yaml create mode 100644 docs/source/examples/parameters.yaml create mode 100644 docs/source/examples/run.yaml diff --git a/docs/source/examples/heat.txt b/docs/source/examples/heat.txt new file mode 100644 index 00000000..7ea565ae --- /dev/null +++ b/docs/source/examples/heat.txt @@ -0,0 +1 @@ +{{thermal_diffusivity}}, {{run_duration}}, {{number_of_columns}}, {{number_of_rows}} diff --git a/docs/source/examples/info.yaml b/docs/source/examples/info.yaml new file mode 100644 index 00000000..a1397b57 --- /dev/null +++ b/docs/source/examples/info.yaml @@ -0,0 +1,8 @@ +summary: | + This model solves the two-dimensional heat equation on a uniform + rectilinear grid. +url: https://github.com/csdms/bmi-example-c +author: CSDMS +email: csdms@colorado.edu +version: 0.2 +license: MIT diff --git a/docs/source/examples/parameters.yaml b/docs/source/examples/parameters.yaml new file mode 100644 index 00000000..3c1c5f2b --- /dev/null +++ b/docs/source/examples/parameters.yaml @@ -0,0 +1,42 @@ +run_duration: + description: Simulation run time + value: + type: float + default: 1.0 + units: s + range: + min: 0.0 + max: 1000000.0 + +thermal_diffusivity: + name: Thermal diffusivity + description: Thermal diffusivity + value: + type: float + default: 1.0 + range: + min: 0.0 + max: 10.0 + units: 'm2 s-1' + +number_of_rows: + name: Number of rows + description: Number of grid rows + value: + type: int + default: 10 + range: + min: 0 + max: 10000 + units: '1' + +number_of_columns: + name: Number of columns + description: Number of grid columns + value: + type: int + default: 10 + range: + min: 0 + max: 10000 + units: '1' diff --git a/docs/source/examples/run.yaml b/docs/source/examples/run.yaml new file mode 100644 index 00000000..3b0457ff --- /dev/null +++ b/docs/source/examples/run.yaml @@ -0,0 +1 @@ +config_file: heat.txt From 8ed6a642add141da5c31451f813ddecc0f970600 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Thu, 17 Sep 2020 09:14:08 -0600 Subject: [PATCH 24/26] Complete example text This includes a Python script showing how to call the *heat* model in *pymt*. --- docs/source/example.rst | 88 ++++++++++++++++++++++++++- docs/source/examples/heatc_ex.py | 67 ++++++++++++++++++++ docs/source/examples/pymt_heatc_ex.py | 62 +++++++++++++++++++ 3 files changed, 215 insertions(+), 2 deletions(-) create mode 100644 docs/source/examples/heatc_ex.py create mode 100644 docs/source/examples/pymt_heatc_ex.py diff --git a/docs/source/example.rst b/docs/source/example.rst index 10ba15d6..5c2e76f9 100644 --- a/docs/source/example.rst +++ b/docs/source/example.rst @@ -69,7 +69,7 @@ Clone the `bmi-example-c`_ repository from GitHub: $ git clone https://github.com/csdms/bmi-example-c -The repository `README`_ contains general instructions for building and installing +There are general `instructions`_ in the repository for building and installing this package on Linux, macOS, and Windows. We'll augment those instructions with the note that we're installing into the *wrap* conda environment, @@ -254,11 +254,95 @@ ending with if everything has been built correctly. + +Add metadata to make a *pymt* component +--------------------------------------- + +The final step in wrapping the *heat* model +is to add metadata used by the `Python Modeling Tool`_, *pymt*. +CSDMS is developing a set of standards, +the `CSDMS Model Metadata`_, +that provides a detailed and formalized description of a model. +The metadata allow *heat* to be run and and :term:`coupled ` +with other models that expose a BMI and have been similarly wrapped +with the *babelizer*. + +Recall the *babelizer* outputs the wrapped *heat* model +to the directory ``pymt_heatc``. +Under this directory, +the *babelizer* created a directory for *heat* model metadata, +``meta/HeatModel``. +The contents of this directory are currently: + +.. code:: bash + + $ ls meta/HeatModel/ + api.yaml + +The file ``api.yaml`` is automatically generated by the *babelizer*. +To complete the description of the *heat* model, +other metadata files are needed, including: + +* :download:`info.yaml ` +* :download:`run.yaml ` +* a :download:`templated model configuration file ` +* :download:`parameters.yaml ` + +`Descriptions`_ of these files and their roles +are given in the CSDMS Model Metadata repository. +Download each of the files using the links in the list above +and place them in the ``pymt_heatc/meta/HeatModel`` directory +alongside ``api.yaml``. + +Next, install *pymt*: + +.. code:: bash + + $ conda install -c conda-forge pymt + +Then start a Python session and show that the *heat* model +can be called through *pymt*: + +.. code:: python + + >>> from pymt.models import HeatModel + >>> m = HeatModel() + >>> print(m.name) + The 2D Heat Equation + +A longer example, +:download:`pymt_heatc_ex.py `, +is included in the documentation. +For easy viewing, it's reproduced here verbatim: + +.. include:: examples/pymt_heatc_ex.py + :literal: + +:download:`Download ` this Python script, +then run it with: + +.. code:: bash + + $ python pymt_heatc_ex.py + + +Summary +------- + +Using the *babelizer*, we wrapped the *heat* model, which is written in C. +It can now be called as a *pymt* component in Python. + +The steps for wrapping a model with the *babelizer* outlined in this example +can also be applied to models written in C++ and Fortran. + + .. Links .. _bmi-example-c: https://github.com/csdms/bmi-example-c -.. _README: https://github.com/csdms/bmi-example-c/blob/master/README.md +.. _instructions: https://github.com/csdms/bmi-example-c/blob/master/README.md .. _Developer Command Prompt: https://docs.microsoft.com/en-us/dotnet/framework/tools/developer-command-prompt-for-vs .. _bmi-tester: https://github.com/csdms/bmi-tester .. _Python Modeling Tool: https://pymt.readthedocs.io +.. _CSDMS Model Metadata: https://github.com/csdms/model_metadata +.. _Descriptions: https://github.com/csdms/model_metadata/blob/develop/README.rst diff --git a/docs/source/examples/heatc_ex.py b/docs/source/examples/heatc_ex.py new file mode 100644 index 00000000..08d12a30 --- /dev/null +++ b/docs/source/examples/heatc_ex.py @@ -0,0 +1,67 @@ +"""An example of running the heatc model through its BMI.""" +import numpy as np +from pymt_heatc import HeatModel + + +config_file = 'config.txt' +np.set_printoptions(formatter={'float': '{: 6.1f}'.format}) + + +# Instatiate an initialize the model. +m = HeatModel() +print(m.get_component_name()) +m.initialize(config_file) + +# List the model's exchange items. +print('Input vars:', m.get_input_var_names()) +print('Output vars:', m.get_output_var_names()) + +# Get the grid_id for the plate_surface__temperature variable. +var_name = 'plate_surface__temperature' +print('Variable {}'.format(var_name)) +grid_id = m.get_var_grid(var_name) +print(' - grid id:', grid_id) + +# Get grid and variable info for plate_surface__temperature. +print(' - grid type:', m.get_grid_type(grid_id)) +grid_rank = m.get_grid_rank(grid_id) +print(' - rank:', grid_rank) +grid_shape = np.empty(grid_rank, dtype=np.int32) +m.get_grid_shape(grid_id, grid_shape) +print(' - shape:', grid_shape) +grid_size = m.get_grid_size(grid_id) +print(' - size:', grid_size) +grid_spacing = np.empty(grid_rank, dtype=np.float) +m.get_grid_spacing(grid_id, grid_spacing) +print(' - spacing:', grid_spacing) +grid_origin = np.empty(grid_rank, dtype=np.float) +m.get_grid_origin(grid_id, grid_origin) +print(' - origin:', grid_origin) +print(' - variable type:', m.get_var_type(var_name)) +print(' - units:', m.get_var_units(var_name)) +print(' - itemsize:', m.get_var_itemsize(var_name)) +print(' - nbytes:', m.get_var_nbytes(var_name)) + +# Get the initial temperature values. +val = np.empty(grid_shape, dtype=np.float) +m.get_value(var_name, val) +print(' - initial values (gridded):') +print(val.reshape(np.roll(grid_shape, 1))) + +# Get time information from the model. +print('Start time:', m.get_start_time()) +print('End time:', m.get_end_time()) +print('Current time:', m.get_current_time()) +print('Time step:', m.get_time_step()) +print('Time units:', m.get_time_units()) + +# Advance the model by one time step. +m.update() +print('Updated time:', m.get_current_time()) + +# Advance the model until a later time. +m.update_until(5.0) +print('Later time:', m.get_current_time()) + +# Finalize the model. +m.finalize() diff --git a/docs/source/examples/pymt_heatc_ex.py b/docs/source/examples/pymt_heatc_ex.py new file mode 100644 index 00000000..e4bc023b --- /dev/null +++ b/docs/source/examples/pymt_heatc_ex.py @@ -0,0 +1,62 @@ +"""Run the heat model in pymt.""" +import numpy as np +from pymt.models import HeatModel + + +# Instantiate the component and get its name. +m = HeatModel() +print(m.name) + +# Call setup, then initialize the model. +args = m.setup('.') +m.initialize(*args) + +# List the model's exchange items. +print('Number of input vars:', len(m.input_var_names)) +for var in m.input_var_names: + print(' - {}'.format(var)) +print('Number of output vars:', len(m.output_var_names)) +for var in m.output_var_names: + print(' - {}'.format(var)) + +# Get variable info. +var_name = m.output_var_names[0] +print('Variable {}'.format(var_name)) +print(' - variable type:', m.var_type(var_name)) +print(' - units:', m.var_units(var_name)) +print(' - itemsize:', m.var_itemsize(var_name)) +print(' - nbytes:', m.var_nbytes(var_name)) +print(' - location:', m.var_location(var_name)) + +# Get grid info for variable. +grid_id = m.var_grid(var_name) +print(' - grid id:', grid_id) +print(' - grid type:', m.grid_type(grid_id)) +print(' - rank:', m.grid_ndim(grid_id)) +print(' - size:', m.grid_node_count(grid_id)) +print(' - shape:', m.grid_shape(grid_id)) + +# Get time information from the model. +print('Start time:', m.start_time) +print('End time:', m.end_time) +print('Current time:', m.time) +print('Time step:', m.time_step) +print('Time units:', m.time_units) + +# Get the initial values of the variable. +print('Get values of {}...'.format(var_name)) +val = m.var[var_name].data +print(' - values at time {}:'.format(m.time)) +print(val) + +# Advance the model by one time step. +m.update() +print('Update: current time:', m.time) + +# Advance the model until a later time. +m.update_until(5.0) +print('Update: current time:', m.time) + +# Finalize the model. +m.finalize() +print('Done.') From 86af54c5b6209acaf82319ea9db4667b4a95e1d0 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Thu, 17 Sep 2020 13:48:38 -0600 Subject: [PATCH 25/26] Add rtfd badge --- README.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index 49bf664e..fa127667 100644 --- a/README.rst +++ b/README.rst @@ -1,6 +1,10 @@ .. image:: https://img.shields.io/travis/csdms/babelizer.svg :target: https://travis-ci.org/csdms/babelizer +.. image:: https://readthedocs.org/projects/babelizer/badge/?version=latest + :target: https://babelizer.readthedocs.io/en/latest/?badge=latest + :alt: Documentation Status + .. image:: https://img.shields.io/badge/code%20style-black-000000.svg :target: https://github.com/csdms/babelizer @@ -15,8 +19,8 @@ Wrap BMI libraries with Python bindings About ***** -The *babelizer* is a utility for wrapping libraries, from a variety for -languages, that expose a Basic Model Interface (BMI) so that they can +The *babelizer* is a utility for wrapping libraries, from a variety of +languages, that expose a Basic Model Interface (BMI) so that they can be imported as a Python package. From 1c0617e698514432cf4d97cc186335d2eb99790f Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Thu, 17 Sep 2020 13:49:13 -0600 Subject: [PATCH 26/26] Edit/improve text --- docs/source/example.rst | 11 +++++------ docs/source/index.rst | 2 +- 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/source/example.rst b/docs/source/example.rst index 5c2e76f9..f8a461ba 100644 --- a/docs/source/example.rst +++ b/docs/source/example.rst @@ -33,16 +33,15 @@ create a directory to hold our work: Set up a conda environment -------------------------- -Start by setting up a :term:`conda environment` -that includes a toolchain to build and install the model, -as well as the *babelizer*. +Start by setting up a :term:`conda environment` that includes the *babelizer*, +as well as a toolchain to build and install the model. The necessary packages are listed in the conda environment file :download:`environment.yml`: .. include:: environment.yml :literal: -Download :download:`this file ` +:download:`Download ` this file and create the new environment with: .. code:: bash @@ -208,7 +207,7 @@ at the end of which you'll hopefully see: Successfully installed pymt-heatc -Take a moment to pause and see what we've done. +Pause a moment to see what we've done. Start a Python session and try the following commands: .. code:: python @@ -260,7 +259,7 @@ Add metadata to make a *pymt* component The final step in wrapping the *heat* model is to add metadata used by the `Python Modeling Tool`_, *pymt*. -CSDMS is developing a set of standards, +CSDMS develops a set of standards, the `CSDMS Model Metadata`_, that provides a detailed and formalized description of a model. The metadata allow *heat* to be run and and :term:`coupled ` diff --git a/docs/source/index.rst b/docs/source/index.rst index cd5c449b..fe96c93c 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -10,7 +10,7 @@ The *babelizer* is an open source Python utility, developed by the `Community Surface Dynamics Modeling System`_ (CSDMS), for wrapping models that expose a `Basic Model Interface`_ (BMI) -so they can imported as Python packages. +so they can be imported as Python packages. Supported languages include: