Skip to content

Commit 43d5271

Browse files
softwareengineerprogrammersoftwareengineerprogrammer
committed
Move Getting Started Guide to INSTALL.rst
1 parent 120e6f3 commit 43d5271

File tree

2 files changed

+174
-168
lines changed

2 files changed

+174
-168
lines changed

‎INSTALL.rst

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
Getting Started
2+
===============
3+
4+
Web Interface
5+
-------------
6+
7+
A web interface is available at `gtp.scientificwebservices.com/geophires <https://gtp.scientificwebservices.com/geophires>`__.
8+
9+
The short URL `bit.ly/geophires <https://bit.ly/geophires>`__ redirects to the same location.
10+
11+
Installation
12+
------------
13+
14+
Pip Package
15+
^^^^^^^^^^^
16+
17+
If you do not need to view or edit GEOPHIRES-X source code, you can consume GEOPHIRES-X as a regular, non-editable python package::
18+
19+
pip3 install https://github.com/NREL/GEOPHIRES-X/archive/main.zip
20+
21+
22+
.. (Eventually package will be published to PyPi, enabling ``pip install geophires-x``)
23+
24+
25+
Editable Installation (Recommended)
26+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
27+
28+
An editable installation is recommended for most users. It will allow you to run GEOPHIRES-X locally,
29+
view its Python files in an IDE or text editor,
30+
and create your own extensions as described in `How to extend GEOPHIRES-X <docs/How-to-extend-GEOPHIRES-X.md#how-to-extend-geophires-x>`__.
31+
32+
Prerequisites:
33+
34+
1. Python 3.8+: You must have Python 3.8 or later installed on your machine. Python can be downloaded at `python.org/downloads <https://www.python.org/downloads/>`__. (On Ubuntu: ``alias python=python3`` if not aliased already.)
35+
2. `Git <https://git-scm.com/book/en/v2/Getting-Started-Installing-Git>`__
36+
3. Virtual environment (aka ``virtualenv``): `Install virtual environment on your machine <https://virtualenv.pypa.io/en/latest/installation.html#via-pip>`__ if you don't have it already
37+
4. On Windows, you will need Admin privileges (required to successfully activate the virtual environment)
38+
39+
Steps:
40+
41+
1. Open a command line (i.e. Terminal on Mac, PowerShell on Windows)
42+
2. Create a directory for GEOPHIRES::
43+
44+
mkdir my-geophires-project
45+
cd my-geophires-project
46+
47+
3. Create a virtual environment::
48+
49+
python -m venv venv
50+
51+
4. Source the virtual environment:
52+
53+
- Windows::
54+
55+
venv\Scripts\activate
56+
57+
- macOS/Linux::
58+
59+
source venv/bin/activate
60+
61+
5. Install the ``geophires-x`` package::
62+
63+
pip3 install -e git+https://github.com/NREL/GEOPHIRES-X.git#egg=geophires-x --src .
64+
65+
6. Run on an example file::
66+
67+
cd geophires-x
68+
cd tests
69+
cd examples
70+
python -mgeophires_x example1.txt
71+
72+
7. View and edit source code by opening the ``my-geophires-project/`` directory in an IDE or editor such as `PyCharm <https://www.jetbrains.com/pycharm/>`__, `Spyder <https://www.spyder-ide.org/>`__, or `Visual Studio Code <https://code.visualstudio.com/>`__. The GEOPHIRES-X source code will be located in the ``my-geophires-project/geophires-x`` directory. You can add your own python files in ``my-geophires-x/`` that use the source as a module as shown below.
73+
74+
To update the editable installation with the latest GEOPHIRES version::
75+
76+
cd geophires-x
77+
git pull
78+
# resolve merge conflicts, if any
79+
pip install -e .
80+
81+
82+
83+
Usage
84+
-----
85+
86+
Python
87+
^^^^^^
88+
89+
Example usage in Python:
90+
91+
.. code:: python
92+
93+
from geophires_x_client import GeophiresXClient
94+
from geophires_x_client.geophires_input_parameters import GeophiresInputParameters
95+
96+
client = GeophiresXClient()
97+
result = client.get_geophires_result(
98+
GeophiresInputParameters({
99+
"Gradient 1": "69",
100+
"Reservoir Depth": "5",
101+
"End-Use Option": "1",
102+
"Power Plant Type": "4"
103+
})
104+
)
105+
106+
with open(result.output_file_path, 'r') as f:
107+
print(f.read())
108+
109+
If you followed the editable installation example above, put this code in ``my-geophires-project/main.py``, then run::
110+
111+
python main.py
112+
113+
You will then see output including a case report::
114+
115+
(venv) ➜ my-geophires-project python main.py
116+
No valid plant outlet pressure provided. GEOPHIRES will assume default plant outlet pressure (100 kPa)
117+
No valid plant outlet pressure provided. GEOPHIRES will assume default plant outlet pressure (100 kPa)
118+
119+
*****************
120+
***CASE REPORT***
121+
*****************
122+
123+
Simulation Metadata
124+
----------------------
125+
GEOPHIRES Version: 3.4.42
126+
Simulation Date: 2024-07-08
127+
Simulation Time: 10:07
128+
Calculation Time: 0.047 sec
129+
130+
***SUMMARY OF RESULTS***
131+
132+
End-Use Option: Electricity
133+
Average Net Electricity Production: 23.94 MW
134+
Electricity breakeven price: 5.04 cents/kWh
135+
136+
[...]
137+
138+
139+
You may also pass parameters as a text file:
140+
141+
.. code:: python
142+
143+
from pathlib import Path
144+
from geophires_x_client import GeophiresXClient
145+
from geophires_x_client.geophires_input_parameters import GeophiresInputParameters
146+
147+
# https://github.com/NREL/GEOPHIRES-X/blob/main/tests/examples/example1.txt
148+
example_file_path = Path('geophires-x/tests/examples/example1.txt').absolute()
149+
150+
client = GeophiresXClient()
151+
result = client.get_geophires_result(
152+
GeophiresInputParameters(from_file_path=example_file_path)
153+
)
154+
155+
with open(result.output_file_path, 'r') as f:
156+
print(f.read())
157+
158+
159+
`test_geophires_x.py <tests/test_geophires_x.py>`__ has additional examples of how to consume and call `GeophiresXClient <src/geophires_x_client/__init__.py#L14>`__.
160+
161+
162+
Command Line
163+
^^^^^^^^^^^^
164+
165+
If you installed with pip (editable or non-), you may run GEOPHIRES from the command line, passing your input file as an argument::
166+
167+
python -mgeophires_x my_geophires_input.txt
168+
169+
You may also optionally pass the output file as well::
170+
171+
python -mgeophires_x my_geophires_input.txt my_geophires_result.out
172+
173+
(If you do not pass an output file argument a default name will be used.)

‎README.rst

Lines changed: 1 addition & 168 deletions
Original file line numberDiff line numberDiff line change
@@ -81,176 +81,9 @@ Free software: `MIT license <LICENSE>`__
8181
Getting Started
8282
===============
8383

84-
Web Interface
85-
-------------
86-
8784
A web interface is available at `gtp.scientificwebservices.com/geophires <https://gtp.scientificwebservices.com/geophires>`__.
8885

89-
The short URL `bit.ly/geophires <https://bit.ly/geophires>`__ redirects to the same location.
90-
91-
Installation
92-
------------
93-
94-
Pip Package
95-
^^^^^^^^^^^
96-
97-
If you do not need to view or edit GEOPHIRES-X source code, you can consume GEOPHIRES-X as a regular, non-editable python package::
98-
99-
pip3 install https://github.com/NREL/GEOPHIRES-X/archive/main.zip
100-
101-
102-
.. (Eventually package will be published to PyPi, enabling ``pip install geophires-x``)
103-
104-
105-
Editable Installation (Recommended)
106-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
107-
108-
An editable installation is recommended for most users. It will allow you to run GEOPHIRES-X locally,
109-
view its Python files in an IDE or text editor,
110-
and create your own extensions as described in `How to extend GEOPHIRES-X <docs/How-to-extend-GEOPHIRES-X.md#how-to-extend-geophires-x>`__.
111-
112-
Prerequisites:
113-
114-
1. Python 3.8+: You must have Python 3.8 or later installed on your machine. Python can be downloaded at `python.org/downloads <https://www.python.org/downloads/>`__. (On Ubuntu: ``alias python=python3`` if not aliased already.)
115-
2. `Git <https://git-scm.com/book/en/v2/Getting-Started-Installing-Git>`__
116-
3. Virtual environment (aka ``virtualenv``): `Install virtual environment on your machine <https://virtualenv.pypa.io/en/latest/installation.html#via-pip>`__ if you don't have it already
117-
4. On Windows, you will need Admin privileges (required to successfully activate the virtual environment)
118-
119-
Steps:
120-
121-
1. Open a command line (i.e. Terminal on Mac, PowerShell on Windows)
122-
2. Create a directory for GEOPHIRES::
123-
124-
mkdir my-geophires-project
125-
cd my-geophires-project
126-
127-
3. Create a virtual environment::
128-
129-
python -m venv venv
130-
131-
4. Source the virtual environment:
132-
133-
- Windows::
134-
135-
venv\Scripts\activate
136-
137-
- macOS/Linux::
138-
139-
source venv/bin/activate
140-
141-
5. Install the ``geophires-x`` package::
142-
143-
pip3 install -e git+https://github.com/NREL/GEOPHIRES-X.git#egg=geophires-x --src .
144-
145-
6. Run on an example file::
146-
147-
cd geophires-x
148-
cd tests
149-
cd examples
150-
python -mgeophires_x example1.txt
151-
152-
7. View and edit source code by opening the ``my-geophires-project/`` directory in an IDE or editor such as `PyCharm <https://www.jetbrains.com/pycharm/>`__, `Spyder <https://www.spyder-ide.org/>`__, or `Visual Studio Code <https://code.visualstudio.com/>`__. The GEOPHIRES-X source code will be located in the ``my-geophires-project/geophires-x`` directory. You can add your own python files in ``my-geophires-x/`` that use the source as a module as shown below.
153-
154-
To update the editable installation with the latest GEOPHIRES version::
155-
156-
cd geophires-x
157-
git pull
158-
# resolve merge conflicts, if any
159-
pip install -e .
160-
161-
162-
163-
Usage
164-
-----
165-
166-
Python
167-
^^^^^^
168-
169-
Example usage in Python:
170-
171-
.. code:: python
172-
173-
from geophires_x_client import GeophiresXClient
174-
from geophires_x_client.geophires_input_parameters import GeophiresInputParameters
175-
176-
client = GeophiresXClient()
177-
result = client.get_geophires_result(
178-
GeophiresInputParameters({
179-
"Gradient 1": "69",
180-
"Reservoir Depth": "5",
181-
"End-Use Option": "1",
182-
"Power Plant Type": "4"
183-
})
184-
)
185-
186-
with open(result.output_file_path, 'r') as f:
187-
print(f.read())
188-
189-
If you followed the editable installation example above, put this code in ``my-geophires-project/main.py``, then run::
190-
191-
python main.py
192-
193-
You will then see output including a case report::
194-
195-
(venv) ➜ my-geophires-project python main.py
196-
No valid plant outlet pressure provided. GEOPHIRES will assume default plant outlet pressure (100 kPa)
197-
No valid plant outlet pressure provided. GEOPHIRES will assume default plant outlet pressure (100 kPa)
198-
199-
*****************
200-
***CASE REPORT***
201-
*****************
202-
203-
Simulation Metadata
204-
----------------------
205-
GEOPHIRES Version: 3.4.42
206-
Simulation Date: 2024-07-08
207-
Simulation Time: 10:07
208-
Calculation Time: 0.047 sec
209-
210-
***SUMMARY OF RESULTS***
211-
212-
End-Use Option: Electricity
213-
Average Net Electricity Production: 23.94 MW
214-
Electricity breakeven price: 5.04 cents/kWh
215-
216-
[...]
217-
218-
219-
You may also pass parameters as a text file:
220-
221-
.. code:: python
222-
223-
from pathlib import Path
224-
from geophires_x_client import GeophiresXClient
225-
from geophires_x_client.geophires_input_parameters import GeophiresInputParameters
226-
227-
# https://github.com/NREL/GEOPHIRES-X/blob/main/tests/examples/example1.txt
228-
example_file_path = Path('geophires-x/tests/examples/example1.txt').absolute()
229-
230-
client = GeophiresXClient()
231-
result = client.get_geophires_result(
232-
GeophiresInputParameters(from_file_path=example_file_path)
233-
)
234-
235-
with open(result.output_file_path, 'r') as f:
236-
print(f.read())
237-
238-
239-
`test_geophires_x.py <tests/test_geophires_x.py>`__ has additional examples of how to consume and call `GeophiresXClient <src/geophires_x_client/__init__.py#L14>`__.
240-
241-
242-
Command Line
243-
^^^^^^^^^^^^
244-
245-
If you installed with pip (editable or non-), you may run GEOPHIRES from the command line, passing your input file as an argument::
246-
247-
python -mgeophires_x my_geophires_input.txt
248-
249-
You may also optionally pass the output file as well::
250-
251-
python -mgeophires_x my_geophires_input.txt my_geophires_result.out
252-
253-
(If you do not pass an output file argument a default name will be used.)
86+
To run GEOPHIRES locally or to modify the source code, see the `Getting Started Guide <INSTALL.rst>`__.
25487

25588

25689
Documentation

0 commit comments

Comments
 (0)