Quick Start for Developers

This guide provides a condensed overview for developers to get started with MPAS-Analysis development.

1. Fork and Clone the Repository

Fork MPAS-Analysis on GitHub.

Clone the main repo and your fork locally: - Create a base directory (e.g., mpas-analysis). - Clone the main repo:

git clone git@github.com:MPAS-Dev/MPAS-Analysis.git develop

Add your fork as a remote:

git remote add <username>/MPAS-Analysis git@github.com:<username>/MPAS-Analysis.git

2. Configure Git

Set up your ~/.gitconfig with your name and email (must match your GitHub account).
Recommended: set editor, color, and useful aliases.

3. Set Up SSH Keys

Add SSH keys to GitHub for push access.
See: https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account

4. Create a Development Worktree

Fetch latest changes:
git fetch --all -p
Create a worktree for your feature branch:
git worktree add ../<feature_branch>
Enter the worktree directory:
cd ../<feature_branch>

5. Set Up the Development Environment

Install pixi by following the official installation instructions at pixi.sh. On Linux and macOS, a common option is:
```
curl -fsSL https://pixi.sh/install.sh | sh
```
From the root of your worktree, create and activate the development environment:
```
pixi shell
```
pixi shell will create the default environment on first use and activate it with MPAS-Analysis installed in editable mode.

6. Activate Environment (each session)

From the root of your worktree, run:
```
pixi shell
```
To run the analysis regression suite from the same Pixi environment:
```
./suite/run_suite.bash --dev
```

7. Configure and Run MPAS-Analysis

Copy and edit a config file (e.g., example_e3sm.cfg) for your run.
Set required options: mainRunName, baseDirectory, mpasMeshName, output paths.
Set mapMpiTasks = 1 and mapParallelExec = None for development environments.

Export HDF5 file locking variable if needed: - Bash:

export HDF5_USE_FILE_LOCKING=FALSE

Csh:
```
setenv HDF5_USE_FILE_LOCKING FALSE
```

Run analysis:

mpas_analysis -m <machine> <your_config>.cfg

8. View Results

Output is a set of web pages in your specified output directory.
On some systems, update permissions:
chmod -R ugo+rX <output_dir>
See the main web page for links to results and provenance info.

Additional Recommendations

Use VS Code for remote editing and linting (optional).

For more details, see the full Developer: Getting Started.