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 repo, we noticed there is currently no README.md. Here's what we'd suggest adding:
Sections to add (not currently in your repo):
- Overview
- Screenshots
- Features
- Requirements
- App Installation
- Configuration (
form.yml attributes table)
- Troubleshooting
- Testing
- Known Limitations
- Contributing
- References
- License
- Acknowledgments
Sections that could be expanded:
- (none -- the repo has no existing README)
Sections already present:
- (none -- the repo has no existing README)
Below we've provided two versions: a diff showing exactly what we're suggesting to add, 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 Mathematica
+
+ 
+ [](https://opensource.org/licenses/MIT)
+
+ ## Overview
+
+ An [Open OnDemand](https://openondemand.org/) Batch Connect app that launches
+ a [Mathematica](https://www.wolfram.com/mathematica/) desktop session via VNC
+ on OSC HPC clusters. Mathematica is a computational software program used in
+ many scientific, engineering, mathematical, and computing fields.
+
+ This app uses the Batch Connect `vnc` template with Slurm and supports
+ cluster: Pitzer.
+
+ - **Upstream project:** [Mathematica](https://www.wolfram.com/mathematica/)
+ - **Batch Connect template:** `vnc`
+ - **Scheduler:** Slurm
+
+ ## Screenshots
+
+ <!-- TODO: Add a screenshot of the app's launch form or a running session -->
+
+ ## Features
+
+ - Launches Mathematica 13.2.1 in a VNC desktop session with Xfce window manager
+ - GPU-enabled node types (40-core GPU, 48-core GPU)
+ - Multiple node types: standard compute (40/48 core), GPU, largemem, hugemem, debug
+ - Configurable core count (1--48, varies by node type)
+ - Module-based software loading via Lmod (`mathematica/13.2.1`)
+
+ ## 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):
+
+ - [Lmod](https://www.tacc.utexas.edu/research-development/tacc-projects/lmod)
+ or any other `module restore` and `module load <modules>` based CLI
+ - [Mathematica](https://www.wolfram.com/mathematica/) (currently loads
+ `mathematica/13.2.1`)
+ - [Xfce](https://xfce.org/) desktop environment (xfwm4, xfce4-panel,
+ xfsettingsd)
+ - A VNC server (e.g., TurboVNC)
+
+ ### Open OnDemand
+
+ <!-- TODO: Specify the minimum OOD version this app has been tested with -->
+ - Slurm scheduler
+ - Batch Connect VNC template support
+
+ ## App Installation
+
+ ### 1. Clone the repository
+
+ ```sh
+ cd /var/www/ood/apps/sys
+ git clone https://github.com/OSC/bc_osc_mathematica.git
+ cd bc_osc_mathematica
+
+ # Pin to a release (recommended)
+ git checkout v0.5.0
+ ```
+
+ 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` | `pitzer` | Your cluster name(s) |
+ | `node_type` | OSC-specific node types | Node types available on your cluster |
+ | `num_cores` | max `48` | Max cores on your compute nodes |
+
+ In `script.sh.erb`, the app loads modules with:
+ ```
+ module load mathematica/13.2.1
+ ```
+ Update the version to match what is available on your system.
+
+ ### 3. Update the app
+
+ ```sh
+ cd /var/www/ood/apps/sys/bc_osc_mathematica
+ git fetch
+ git checkout <tag>
+ ```
+
+ No restart is needed.
+
+ ## Configuration
+
+ ### form.yml attributes
+
+ | Attribute | Widget | Description | Default |
+ |--------------|--------------|-------------------------------------------------------|-----------|
+ | `cluster` | select | Target cluster ID(s) | `pitzer` |
+ | `bc_num_hours` | number | Maximum wall time (hours) | <!-- TODO: specify default --> |
+ | `num_cores` | number_field | Number of CPU cores (1--48, varies by node type) | `1` |
+ | `node_type` | select | Compute node type (any, 48 core, 40 core, any gpu, 40 core gpu, 48 core gpu, largemem, hugemem, debug) | `any` |
+
+ ## 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_mathematica/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_mathematica/issues).
+
+ ## References
+
+ - [Mathematica](https://www.wolfram.com/mathematica/) -- 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)
+
+ ## License
+
+ <!-- TODO: Specify your license (MIT, CC-BY-4.0, etc.) -->
+
+ ## Acknowledgments
+
+ <!-- TODO: Add funding or institutional support information -->
Clean README.md -- copy-paste ready
# Batch Connect - OSC Mathematica
[](https://opensource.org/licenses/MIT)
## Overview
An [Open OnDemand](https://openondemand.org/) Batch Connect app that launches
a [Mathematica](https://www.wolfram.com/mathematica/) desktop session via VNC
on OSC HPC clusters. Mathematica is a computational software program used in
many scientific, engineering, mathematical, and computing fields.
This app uses the Batch Connect `vnc` template with Slurm and supports
cluster: Pitzer.
- **Upstream project:** [Mathematica](https://www.wolfram.com/mathematica/)
- **Batch Connect template:** `vnc`
- **Scheduler:** Slurm
## Screenshots
<!-- TODO: Add a screenshot of the app's launch form or a running session -->
## Features
- Launches Mathematica 13.2.1 in a VNC desktop session with Xfce window manager
- GPU-enabled node types (40-core GPU, 48-core GPU)
- Multiple node types: standard compute (40/48 core), GPU, largemem, hugemem, debug
- Configurable core count (1--48, varies by node type)
- Module-based software loading via Lmod (`mathematica/13.2.1`)
## 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):
- [Lmod](https://www.tacc.utexas.edu/research-development/tacc-projects/lmod)
or any other `module restore` and `module load <modules>` based CLI
- [Mathematica](https://www.wolfram.com/mathematica/) (currently loads
`mathematica/13.2.1`)
- [Xfce](https://xfce.org/) desktop environment (xfwm4, xfce4-panel,
xfsettingsd)
- A VNC server (e.g., TurboVNC)
### Open OnDemand
<!-- TODO: Specify the minimum OOD version this app has been tested with -->
- Slurm scheduler
- Batch Connect VNC template support
## App Installation
### 1. Clone the repository
```sh
cd /var/www/ood/apps/sys
git clone https://github.com/OSC/bc_osc_mathematica.git
cd bc_osc_mathematica
# Pin to a release (recommended)
git checkout v0.5.0
```
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` | `pitzer` | Your cluster name(s) |
| `node_type` | OSC-specific node types | Node types available on your cluster |
| `num_cores` | max `48` | Max cores on your compute nodes |
In `script.sh.erb`, the app loads modules with:
```
module load mathematica/13.2.1
```
Update the version to match what is available on your system.
### 3. Update the app
```sh
cd /var/www/ood/apps/sys/bc_osc_mathematica
git fetch
git checkout <tag>
```
No restart is needed.
## Configuration
### form.yml attributes
| Attribute | Widget | Description | Default |
|--------------|--------------|-------------------------------------------------------|-----------|
| `cluster` | select | Target cluster ID(s) | `pitzer` |
| `bc_num_hours` | number | Maximum wall time (hours) | <!-- TODO: specify default --> |
| `num_cores` | number_field | Number of CPU cores (1--48, varies by node type) | `1` |
| `node_type` | select | Compute node type (any, 48 core, 40 core, any gpu, 40 core gpu, 48 core gpu, largemem, hugemem, debug) | `any` |
## 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_mathematica/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_mathematica/issues).
## References
- [Mathematica](https://www.wolfram.com/mathematica/) -- 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)
## License
<!-- TODO: Specify your license (MIT, CC-BY-4.0, etc.) -->
## 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.
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 repo, we noticed there is currently no README.md. Here's what we'd suggest adding:
Sections to add (not currently in your repo):
form.ymlattributes table)Sections that could be expanded:
Sections already present:
Below we've provided two versions: a diff showing exactly what we're suggesting to add, 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
Clean README.md -- copy-paste ready
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.