Skip to content

Add community health elements to README #17

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mdpiper merged 1 commit into from
Sep 25, 2026
Merged

Add community health elements to README #17

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
254 changes: 192 additions & 62 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,69 +1,199 @@
# diffusion-model

A numerical model used in the [CSDMS Roadshow](https://csdms.colorado.edu/wiki/Roadshows).
See the [project wiki](https://github.com/csdms/diffusion-model/wiki)
for an overview and development plan for the model.

## Overview

We will develop a one-dimensional numerical model of the physical process of diffusion.
We'll use the forward in time, centered in space (FTCS) finite difference method to solve the diffusion equation,
and we'll apply Dirichlet boundary conditions.

We'll prototype the model in a Jupyter notebook,
then we'll convert the notebook to Python source code--first to a script, then to a packaged module--for more robust use.

Along the way, we'll use the development of the model to explore:

* concepts in Python (imports, loops, conditionals, arrays, functions)
* software tools (shell, Git, conda)
* software development practices (unit testing, refactoring, documentation, packaging)

Although the model is simple,
the topics we cover in developing it are reusable.

### Development plan

Here are the topics we'll cover to develop our model.

* Project Jupyter ([Reference](https://github.com/csdms/ivy/blob/main/lessons/jupyter/index.md))
* JupyterHub: login to the *explore* Hub
* JupyterLab: show components
* Notebook: add commands in a new notebook
* Shell (bash) commands ([Reference](https://github.com/csdms/ivy/blob/main/lessons/shell/index.md))
* Build a diffusion model in a notebook ([Reference](https://github.com/csdms/ivy/blob/main/lessons/python/index.ipynb))
* Python libraries
* NumPy arrays
* Loops
* Conditionals
* Basic plotting with Matplotlib
* Version control with Git and GitHub ([Reference](https://github.com/csdms/ivy/blob/main/lessons/git/index.md))
* Set up SSH keys
* Create a repository for the diffusion model notebook
* Clone the repository to the *explore* Hub
* Export a notebook to Python source code
* Text editors and IDEs ([Reference](https://github.com/csdms/ivy/blob/main/lessons/editors/index.md))
* Virtual environments ([Reference](https://github.com/csdms/ivy/blob/main/lessons/conda/environments.ipynb))
* Use `conda`
* Use `venv` or `virtualenv`
* Refactor the diffusion model
* Modularize model script with functions
* Create a feature branch with Git
* Organize changes with a pull request
* Unit testing ([Reference](https://github.com/csdms/ivy/blob/main/lessons/best-practices/unit-testing.md))
* Lint the model code
* Use `black` and `flake8`
* Package the model ([Reference](https://github.com/csdms/ivy/blob/main/lessons/python/modules.md))
* Write a basic `pyproject.toml` file
* Install model into a virtual environment with `pip`

Here are a few more topics we can cover, given time.

* Use the diffusion model
* Import the diffusion model from new package
* Try to import someone else's diffusion model
* Document the model
* Docstrings
* Sphinx documentation system
* Visualize model output with Jupyter widgets
## Install instructions

Set up a virtual environment and install the model into it, along with its dependencies:

```sh
python -m venv venv
source venv/bin/activate
pip install -e .
```

## Examples

After installing the model, run it from a shell prompt with:

```sh
python -m diffusion_model > model.out
```

View the model output:

```sh
cat model.out
```

```console


Hillslope profile

┌──────────────────────────────────────────────────────────┐
1.0 ┤ !!!!!!!!!!!!!!!!!!!!!!!!!!! │
│ ! │
│ ! │
│ ! │
0.8 ┤ ! │
│ ! │
│ ! │
│ ! │
0.6 ┤ ! │
│ ! │
z │ ! │
│ ! │
0.4 ┤ ! │
│ ! │
│ ! │
│ ! │
0.2 ┤ ! │
│ ! │
│ ! │
│ ! │
│ ! │
0.0 ┤ !!!!!!!!!!!!!!!!!!!!!!!!!!! │
└──┬──────────┬─────────┬──────────┬─────────┬──────────┬──┘
0 20 40 60 80 100

x


Hillslope profile

┌──────────────────────────────────────────────────────────┐
1.0 ┤ !!!!!!!!!!!!!! │
│ !!! │
│ !! │
│ ! │
0.8 ┤ !! │
│ !! │
│ ! │
│ !! │
0.6 ┤ ! │
│ !! │
z │ ! │
│ ! │
0.4 ┤ !! │
│ ! │
│ !! │
│ ! │
0.2 ┤ !! │
│ !! │
│ !!! │
│ !!! │
│ !!!!!! │
0.0 ┤ !!!!!!!!! │
└──┬──────────┬─────────┬──────────┬─────────┬──────────┬──┘
0 20 40 60 80 100

x
0.000000
0.000133
0.000278
0.000449
0.000659
0.000927
0.001271
0.001714
0.002285
0.003018
0.003951
0.005131
0.006612
0.008457
0.010737
0.013532
0.016931
0.021032
0.025941
0.031770
0.038636
0.046662
0.055970
0.066677
0.078900
0.092743
0.108299
0.125643
0.144829
0.165890
0.188827
0.213615
0.240196
0.268478
0.298337
0.329617
0.362133
0.395672
0.430001
0.464865
0.500000
0.535135
0.569999
0.604328
0.637867
0.670383
0.701663
0.731522
0.759804
0.786385
0.811173
0.834110
0.855171
0.874357
0.891701
0.907257
0.921100
0.933323
0.944030
0.953338
0.961364
0.968230
0.974059
0.978968
0.983069
0.986468
0.989263
0.991543
0.993388
0.994869
0.996049
0.996982
0.997715
0.998286
0.998729
0.999073
0.999341
0.999551
0.999722
0.999867
1.000000
```

## Uninstall instructions

When you're done working with the model, deactivate and delete the virtual environment:

```sh
deactivate
rm -r venv
```

## Contributing

See the [CSDMS contributor guide](https://github.com/csdms/project/blob/main/CONTRIBUTING.md)
for information about contributing to this project.
All contributors are governed by the [CSDMS contributor code of conduct](https://github.com/csdms/project/blob/main/CODE-OF-CONDUCT.md).

## Contact information

To communicate with a human about this project,
visit the [CSDMS Help Desk](https://csdms.colorado.edu/wiki/CSDMS_help_desk)
or sign up for [CSDMS Office Hours](https://csdms.colorado.edu/wiki/OfficeHours).

## Acknowledgments

Expand Down
Loading