Update installation and running documentation#827
Conversation
There was a problem hiding this comment.
Pull request overview
Updates ARC’s documentation to clarify supported OSes, modernize conda-based installation guidance, and improve the reaction input example by showing explicit reaction-family selection.
Changes:
- Extend/clarify OS compatibility wording in installation docs.
- Update installation instructions to use Miniforge/Miniconda and Python 3.12+ environment creation.
- Enhance the running docs’ YAML example by adding a
familykey for reactions, and add new doc link targets for Miniforge/Miniconda.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
| docs/source/running.rst | Adds guidance and an example showing reaction family specification in the input YAML. |
| docs/source/links.txt | Adds link targets for Miniconda/Miniforge to support updated installation docs. |
| docs/source/installation.rst | Updates OS compatibility note and revises conda installation instructions toward Miniforge/Miniconda + Python 3.12+. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| make install-rmg | ||
|
|
||
| To install from source instead:: | ||
| To install from source instead (like a github repo):: |
There was a problem hiding this comment.
Use consistent capitalization for the brand name "GitHub" in the docs.
| To install from source instead (like a github repo):: | |
| To install from source instead (like a GitHub repo):: |
| .. _ubuntu: http://releases.ubuntu.com/18.04/ | ||
| .. _cluster: https://en.wikipedia.org/wiki/Comparison_of_cluster_software | ||
| .. _anaconda: https://www.anaconda.com/distribution/ | ||
| .. _miniconda: https://www.anaconda.com/docs/getting-started/miniconda/main |
There was a problem hiding this comment.
The miniconda link target has a trailing space at the end of the URL, which can break the rendered hyperlink and/or trigger Sphinx link warnings. Remove the trailing whitespace.
| .. _miniconda: https://www.anaconda.com/docs/getting-started/miniconda/main | |
| .. _miniconda: https://www.anaconda.com/docs/getting-started/miniconda/main |
| ARC was only tested on Linux (Ubuntu_ 18.04.1 and 20.04 LTS) and Mac machines. | ||
| We don't expect it to work smoothly on Windows machines. | ||
| ARC was only tested on Linux (Ubuntu_ 18.04.1 until 24.04 LTS & Rocky Linux 8.1) and Mac machines. | ||
| /We don't expect it to work smoothly on Windows machines. |
There was a problem hiding this comment.
The Windows compatibility note has an extra leading "/" character, which will render oddly in the docs. Remove the slash so the sentence reads normally.
| /We don't expect it to work smoothly on Windows machines. | |
| We don't expect it to work smoothly on Windows machines. |
| Clone and setup path | ||
| ^^^^^^^^^^^^^^^^^^^^ | ||
|
|
||
| - Download and install the `Anaconda Python Platform`__ for Python 3.7 or higher if you haven't already. | ||
| - Download and install the `Miniforge`_ or `Miniconda`_ for Python 3.12 or higher if you haven't already. | ||
| - Get git and appropriate compilers if you don't have them already by typing ``sudo apt install git gcc g++ make`` |
There was a problem hiding this comment.
This section is titled "Clone and setup path", but the instructions to add ARC to PYTHONPATH were removed. Elsewhere the docs still reference this section for PYTHONPATH setup (e.g., running ARC via the API). Either reintroduce the PYTHONPATH setup instructions here (or equivalent), or update the other docs to no longer depend on PYTHONPATH being set.
alongd
left a comment
alongd
left a comment
There was a problem hiding this comment.
Thanks @ranbenayoun
I see two copilot commits, squash them if we think these modifications are correct?
I think we need to add the pyrdl installation to the automated workflow, or did make install-all ran smoothly for you and ARC works out of the box now?
Please see some comments below
| of software installed on the same machine, where the communication isn't done via SSH). | ||
|
|
||
| Note: | ||
| ARC was only tested on Linux (Ubuntu_ 18.04.1 and 20.04 LTS) and Mac machines. |
There was a problem hiding this comment.
minor comment: please use relatively short commit message title, then you can add more in the commit message description
| # especially when a reaction can be identified as multiple reaction families. | ||
| reactions: | ||
| - label: N2H4 + NH <=> N2H3 + NH2 | ||
| family: H_Abstraction |
There was a problem hiding this comment.
no need to specify the family in the input file, ARC should do that automatically
There was a problem hiding this comment.
Unless ARC does not determine the right family. I have come across where ARC determines the family to be disprop whereas RMG saw it as H Abstract. I believe it is because it can be both but ARC takes the first family return so one may need to force it. It is good for a user to know this option is available
| To install from source instead (like a github repo):: | ||
|
|
||
| make install-rmg RMG_ARGS=--source | ||
| make install-rmg RMG_ARGS=--source |
There was a problem hiding this comment.
I think we should remove all the small make-install directives, and just tell the users to do make install-all now
There was a problem hiding this comment.
We should do both. Tell the user there is a complete full 'install-all' option (although whether that works without a hitch is yet to be concluded), and then show the user they can have more control. The one big issue with ARC documentation is it does not explain all options available
…ty, adjust installation instructions for Miniforge/Miniconda, and enhance reaction input file examples with family specification.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
calvinp0
force-pushed
the
docs_update
branch
from
58a18ed to
5d7789b
Compare
3 participants
clarify OS compatibity, adjust installation instructions for Miniforge/Miniconda, and enhance reaction input file examples with family specification.