Improve README to match Appverse documentation standard #32
Description
Hi! As part of the OOD Appverse community, we're working to improve documentation consistency across Open OnDemand apps so that deployers at other sites can more easily evaluate, install, and adapt them.
We've put together a README template that covers the key sections deployers typically need when considering an app for their site.
After reviewing your current README, here's what we found:
Sections to add (not currently in your README):
- Screenshots
- Features
- Configuration (
form.ymlattributes table) - Troubleshooting
- Testing
- Known Limitations
- References
- Acknowledgments
Sections that could be expanded:
- Overview -- could mention app type (Batch Connect
vnctemplate), supported COMSOL version (6.2), GPU-accelerated visualization via VirtualGL with Intel runtime, software rendering fallback, and link to the upstream COMSOL product page - Install -- could use the latest release tag (
v0.18.2), addform.ymlconfiguration guidance for deployers at other sites, and include site-specific customization steps including license server configuration - Prerequisites -- could add Open OnDemand version and organize into compute node vs. OOD requirements
Sections already present:
- Prerequisites (compute node software) -- well documented with COMSOL Multiphysics, Xfce Desktop, TurboVNC, websockify, X server, VirtualGL, and Lmod versions
- Contributing -- standard fork-and-PR workflow
- License -- dual-license (MIT for code, CC-BY-4.0 for docs) with COMSOL trademark notice
Below we've provided two versions: a diff showing exactly what we're suggesting to add or change, and a clean copy-paste version you can drop in directly. Lines marked with <!-- TODO --> need your input -- we deliberately left those rather than guessing.
Diff view -- see exactly what's new and changed
# Batch Connect - OSC COMSOL Multiphysics
[](https://opensource.org/licenses/MIT)
- A Batch Connect app designed for OSC OnDemand that launches COMSOL Multiphysics
- within an Owens batch job.
+ ## Overview
+
+ An [Open OnDemand](https://openondemand.org/) Batch Connect app that launches
+ [COMSOL Multiphysics](https://www.comsol.com) as an interactive VNC desktop
+ session on OSC HPC clusters. COMSOL Multiphysics is a simulation platform for
+ modeling and solving multiphysics engineering problems with finite element
+ analysis.
+
+ This app uses the Batch Connect `vnc` template with Slurm and supports the
+ Cardinal cluster. GPU-accelerated visualization is available on vis nodes via
+ VirtualGL; software rendering (`comsol -3drend sw`) is used on non-GPU nodes.
+
+ - **Upstream project:** [COMSOL Multiphysics](https://www.comsol.com)
+ - **Batch Connect template:** `vnc`
+ - **Scheduler:** Slurm
+
+ ## Screenshots
+
+ <!-- TODO: Add a screenshot of the app's launch form or a running session -->
+
+ ## Features
+
+ - Interactive COMSOL Multiphysics GUI via VNC desktop session
+ - GPU-accelerated 3D visualization on vis nodes using VirtualGL
+ (`virtualgl/3.1.1`) with Intel runtime (`intel/2021.10.0`)
+ - Software rendering fallback on non-GPU nodes (`comsol -3drend sw`)
+ - Multi-node support with configurable number of nodes and cores per node
+ - Slurm license management (`comsolscript@osc` license token)
+ - Node type selection: any (96 cores), vis (GPU), hugemem (96 cores, 2TB RAM)
+ - Xfce desktop environment with window manager
- ## Prerequisites
+ ## Requirements
+
+ ### Compute Node Software
This Batch Connect app requires the following software be installed on the
**compute nodes** that the batch job is intended to run on (**NOT** the
OnDemand node):
- - [COMSOL Multiphysics] 5.1+
- - [Xfce Desktop] 4+
+ - [COMSOL Multiphysics](https://www.comsol.com) 5.1+
+ - [Xfce Desktop](https://xfce.org/) 4+
For VNC server support:
- - [TurboVNC] 2.1+
- - [websockify] 0.8.0+
+ - [TurboVNC](http://www.turbovnc.org/) 2.1+
+ - [websockify](https://github.com/novnc/websockify) 0.8.0+
For hardware rendering support:
- - [X server]
- - [VirtualGL] 2.3+
+ - [X server](https://www.x.org/)
+ - [VirtualGL](http://www.virtualgl.org/) 2.3+
- **Optional** software:
+ ### Open OnDemand
- - [Lmod] 6.0.1+ or any other `module purge` and `module load <modules>` based
- CLI used to load appropriate environments within the batch job
+ <!-- TODO: Specify the minimum OOD version this app has been tested with -->
+ - Slurm scheduler
- [COMSOL Multiphysics]: https://www.comsol.com
- [Xfce Desktop]: https://xfce.org/
- [TurboVNC]: http://www.turbovnc.org/
- [websockify]: https://github.com/novnc/websockify
- [X server]: https://www.x.org/
- [VirtualGL]: http://www.virtualgl.org/
- [Lmod]: https://www.tacc.utexas.edu/research-development/tacc-projects/lmod
+ ### Optional
- ## Install
+ - [Lmod](https://www.tacc.utexas.edu/research-development/tacc-projects/lmod)
+ 6.0.1+ or any other `module purge` and `module load <modules>` based CLI
+ used to load appropriate environments within the batch job
- Use git to clone this app and checkout the desired branch/version you want to
- use:
+ ## App Installation
+
+ ### 1. Clone the repository
```sh
- scl enable git19 -- git clone <repo>
- cd <dir>
- scl enable git19 -- git checkout <tag/branch>
+ cd /var/www/ood/apps/sys
+ git clone https://github.com/OSC/bc_osc_comsol.git
+ cd bc_osc_comsol
+
+ # Pin to a release (recommended)
+ git checkout v0.18.2
```
- You will not need to do anything beyond this as all necessary assets are
- installed. You will also not need to restart this app as it isn't a Passenger
- app.
-
- To update the app you would:
-
- ```sh
- cd <dir>
- scl enable git19 -- git fetch
- scl enable git19 -- git checkout <tag/branch>
- ```
+ No restart is needed -- Batch Connect apps are not Passenger apps and are
+ detected automatically.
+
+ ### 2. Configure for your site
+
+ Edit `form.yml` and update these values for your cluster:
+
+ | Attribute | OSC Default | Change to |
+ |------------------|-------------------------|------------------------------------|
+ | `cluster` | `cardinal` | Your cluster name(s) |
+ | `comsol_version` | `comsol/6.2` | COMSOL module version on your system |
+ | `node_type` | `any`, `vis`, `hugemem` | Node types available on your cluster |
+ | `num_cores.max` | `96` | Max cores on your compute nodes |
+
+ In `script.sh.erb`, the app loads modules with:
+ ```
+ module load comsol/<version>
+ ```
+ On vis nodes, it additionally loads `intel/2021.10.0` and `virtualgl/3.1.1`.
+ Ensure equivalent modules are available on your system.
+
+ The `submit.yml.erb` reserves a `comsolscript@osc` license token. Update the
+ license server reference for your site's COMSOL license configuration.
+
+ ### 3. Update the app
+
+ ```sh
+ cd /var/www/ood/apps/sys/bc_osc_comsol
+ git fetch
+ git checkout <tag>
+ ```
- Again, you do not need to restart the app as it isn't a Passenger app.
+ No restart is needed.
+
+ ## Configuration
+
+ ### form.yml attributes
+
+ | Attribute | Widget | Description | Default |
+ |--------------------|--------------|------------------------------------------------|------------------|
+ | `cluster` | select | Target cluster ID(s) | `cardinal` |
+ | `comsol_version` | hidden | COMSOL module version to load | `comsol/6.2` |
+ | `bc_num_hours` | number | Maximum wall time (hours) | <!-- TODO: specify default --> |
+ | `bc_num_slots` | number | Number of nodes | `1` |
+ | `num_cores` | number_field | Number of cores per node (0--96) | `1` |
+ | `node_type` | select | Compute node type (any, vis, hugemem) | `any` |
+ | `bc_vnc_resolution`| text | VNC session resolution | <!-- TODO: specify default --> |
+ | `bc_email_on_started` | checkbox | Email notification when job starts | unchecked |
## Contributing
1. Fork it ( https://github.com/OSC/bc_osc_comsol/fork )
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create a new Pull Request
+ For bugs or feature requests,
+ [open an issue](https://github.com/OSC/bc_osc_comsol/issues).
+
+ ## Troubleshooting
+
+ <!-- TODO: Add troubleshooting tips you've encountered -->
+
+ ## Testing
+
+ <!-- TODO: Update with sites where this app has been deployed -->
+
+ | Site | OOD Version | Scheduler | Status |
+ |---------------------------|----------------|-----------|------------|
+ | Ohio Supercomputer Center | <!-- TODO --> | Slurm | Production |
+
+ ## Known Limitations
+
+ <!-- TODO: Document any known limitations -->
+
+ ## References
+
+ - [COMSOL Multiphysics](https://www.comsol.com) -- the application launched
+ by this app
+ - [Open OnDemand](https://openondemand.org/) -- the HPC portal framework
+ - [OOD Batch Connect app development docs](https://osc.github.io/ood-documentation/latest/app-development.html)
+ - [Changelog](https://github.com/OSC/bc_osc_comsol/blob/master/CHANGELOG.md)
+ -- release history for this app
## License
* Documentation, website content, and logo is licensed under
[CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/)
* Code is licensed under MIT (see LICENSE.txt)
* Any and all COMSOL, brand, product, service and feature names, logos and slogans are trademarks or registered trademarks of COMSOL AB.
+ ## Acknowledgments
+
+ <!-- TODO: Add funding or institutional support information -->Clean README.md -- copy-paste ready
# Batch Connect - OSC COMSOL Multiphysics
[](https://opensource.org/licenses/MIT)
## Overview
An [Open OnDemand](https://openondemand.org/) Batch Connect app that launches
[COMSOL Multiphysics](https://www.comsol.com) as an interactive VNC desktop
session on OSC HPC clusters. COMSOL Multiphysics is a simulation platform for
modeling and solving multiphysics engineering problems with finite element
analysis.
This app uses the Batch Connect `vnc` template with Slurm and supports the
Cardinal cluster. GPU-accelerated visualization is available on vis nodes via
VirtualGL; software rendering (`comsol -3drend sw`) is used on non-GPU nodes.
- **Upstream project:** [COMSOL Multiphysics](https://www.comsol.com)
- **Batch Connect template:** `vnc`
- **Scheduler:** Slurm
## Screenshots
<!-- TODO: Add a screenshot of the app's launch form or a running session -->
## Features
- Interactive COMSOL Multiphysics GUI via VNC desktop session
- GPU-accelerated 3D visualization on vis nodes using VirtualGL
(`virtualgl/3.1.1`) with Intel runtime (`intel/2021.10.0`)
- Software rendering fallback on non-GPU nodes (`comsol -3drend sw`)
- Multi-node support with configurable number of nodes and cores per node
- Slurm license management (`comsolscript@osc` license token)
- Node type selection: any (96 cores), vis (GPU), hugemem (96 cores, 2TB RAM)
- Xfce desktop environment with window manager
## Requirements
### Compute Node Software
This Batch Connect app requires the following software be installed on the
**compute nodes** that the batch job is intended to run on (**NOT** the
OnDemand node):
- [COMSOL Multiphysics](https://www.comsol.com) 5.1+
- [Xfce Desktop](https://xfce.org/) 4+
For VNC server support:
- [TurboVNC](http://www.turbovnc.org/) 2.1+
- [websockify](https://github.com/novnc/websockify) 0.8.0+
For hardware rendering support:
- [X server](https://www.x.org/)
- [VirtualGL](http://www.virtualgl.org/) 2.3+
### Open OnDemand
<!-- TODO: Specify the minimum OOD version this app has been tested with -->
- Slurm scheduler
### Optional
- [Lmod](https://www.tacc.utexas.edu/research-development/tacc-projects/lmod)
6.0.1+ or any other `module purge` and `module load <modules>` based CLI
used to load appropriate environments within the batch job
## App Installation
### 1. Clone the repository
```sh
cd /var/www/ood/apps/sys
git clone https://github.com/OSC/bc_osc_comsol.git
cd bc_osc_comsol
# Pin to a release (recommended)
git checkout v0.18.2
```
No restart is needed -- Batch Connect apps are not Passenger apps and are
detected automatically.
### 2. Configure for your site
Edit `form.yml` and update these values for your cluster:
| Attribute | OSC Default | Change to |
|------------------|-------------------------|------------------------------------|
| `cluster` | `cardinal` | Your cluster name(s) |
| `comsol_version` | `comsol/6.2` | COMSOL module version on your system |
| `node_type` | `any`, `vis`, `hugemem` | Node types available on your cluster |
| `num_cores.max` | `96` | Max cores on your compute nodes |
In `script.sh.erb`, the app loads modules with:
```
module load comsol/<version>
```
On vis nodes, it additionally loads `intel/2021.10.0` and `virtualgl/3.1.1`.
Ensure equivalent modules are available on your system.
The `submit.yml.erb` reserves a `comsolscript@osc` license token. Update the
license server reference for your site's COMSOL license configuration.
### 3. Update the app
```sh
cd /var/www/ood/apps/sys/bc_osc_comsol
git fetch
git checkout <tag>
```
No restart is needed.
## Configuration
### form.yml attributes
| Attribute | Widget | Description | Default |
|--------------------|--------------|------------------------------------------------|------------------|
| `cluster` | select | Target cluster ID(s) | `cardinal` |
| `comsol_version` | hidden | COMSOL module version to load | `comsol/6.2` |
| `bc_num_hours` | number | Maximum wall time (hours) | <!-- TODO: specify default --> |
| `bc_num_slots` | number | Number of nodes | `1` |
| `num_cores` | number_field | Number of cores per node (0--96) | `1` |
| `node_type` | select | Compute node type (any, vis, hugemem) | `any` |
| `bc_vnc_resolution`| text | VNC session resolution | <!-- TODO: specify default --> |
| `bc_email_on_started` | checkbox | Email notification when job starts | unchecked |
## Troubleshooting
<!-- TODO: Add troubleshooting tips you've encountered -->
## Testing
<!-- TODO: Update with sites where this app has been deployed -->
| Site | OOD Version | Scheduler | Status |
|---------------------------|----------------|-----------|------------|
| Ohio Supercomputer Center | <!-- TODO --> | Slurm | Production |
## Known Limitations
<!-- TODO: Document any known limitations -->
## Contributing
1. Fork it ( https://github.com/OSC/bc_osc_comsol/fork )
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create a new Pull Request
For bugs or feature requests,
[open an issue](https://github.com/OSC/bc_osc_comsol/issues).
## References
- [COMSOL Multiphysics](https://www.comsol.com) -- the application launched
by this app
- [Open OnDemand](https://openondemand.org/) -- the HPC portal framework
- [OOD Batch Connect app development docs](https://osc.github.io/ood-documentation/latest/app-development.html)
- [Changelog](https://github.com/OSC/bc_osc_comsol/blob/master/CHANGELOG.md)
-- release history for this app
## License
* Documentation, website content, and logo is licensed under
[CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/)
* Code is licensed under MIT (see LICENSE.txt)
* Any and all COMSOL, brand, product, service and feature names, logos and slogans are trademarks or registered trademarks of COMSOL AB.
## Acknowledgments
<!-- TODO: Add funding or institutional support information -->Feel free to use as much or as little of this as you'd like -- we're happy to discuss any of these suggestions or adjust them to better fit your project.
This review is part of the OOD Appverse Affinity Group documentation effort. If you're interested in collaborating on documentation standards for OOD apps, consider joining the Appverse Affinity Group.