Skip to content

Commit e00c855

Browse files
hqrrrhqrrr
committed
Update documentation
1 parent b3efdb9 commit e00c855

6 files changed

Lines changed: 171 additions & 9 deletions

File tree

‎InstructionsForDevelopers.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,10 @@
33
<!-- TOC -->
44
* [Instructions for Developers](#instructions-for-developers)
55
* [Python library](#python-library)
6+
* [Documentation](#documentation)
67
* [Structure](#structure)
78
* [Grasshopper toolbox](#grasshopper-toolbox)
9+
* [Documentation](#documentation-1)
810
* [Structure](#structure-1)
911
* [FAQ](#faq)
1012
* [Q1: Does Carbonfly support other OpenFOAM versions, such as v8, for use with urbanMicroclimateFoam?](#q1-does-carbonfly-support-other-openfoam-versions-such-as-v8-for-use-with-urbanmicroclimatefoam)
@@ -34,8 +36,13 @@ carbonfly (GitHub Repo)/
3436
└─ README.md # README
3537
```
3638

39+
3740
## Python library
3841

42+
### Documentation
43+
44+
[Python Library Documentation](https://rwth-e3d.github.io/carbonfly/)
45+
3946
### Structure
4047

4148
```
@@ -72,6 +79,10 @@ carbonfly/
7279

7380
## Grasshopper toolbox
7481

82+
### Documentation
83+
84+
[Grasshopper Toolbox Documentation](https://github.com/RWTH-E3D/carbonfly/tree/master/documentation)
85+
7586
### Structure
7687

7788
```

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -131,11 +131,11 @@ See [Examples](./examples)
131131

132132
### Python library
133133

134-
See [Carbonfly GitHub Pages](https://rwth-e3d.github.io/carbonfly/)
134+
See [Python Library Documentation](https://rwth-e3d.github.io/carbonfly/)
135135

136136
### Grasshopper Toolbox
137137

138-
See [Documentation](./documentation)
138+
See [Grasshopper Toolbox Documentation](./documentation)
139139

140140
## Instructions for Developers & FAQs
141141

‎docs/source/carbonfly.rst‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,6 @@ Subpackages
1111

1212
.. toctree::
1313
:maxdepth: 4
14-
:hidden:
1514

1615
carbonfly.pythermalcomfort
1716

@@ -20,7 +19,6 @@ Submodules
2019

2120
.. toctree::
2221
:maxdepth: 4
23-
:hidden:
2422

2523
carbonfly.blockmesh_writer
2624
carbonfly.boundary

‎docs/source/index.rst‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,17 +3,18 @@
33
You can adapt this file completely to your liking, but it should at least
44
contain the root `toctree` directive.
55
6-
Carbonfly documentation
7-
=======================
6+
Carbonfly Python library
7+
========================
88

99
**Version:** |release|
1010

1111
.. include:: introduction.rst
1212

1313
.. toctree::
14-
:maxdepth: 4
14+
:maxdepth: 2
1515
:caption: GETTING STARTED:
1616

17+
installation
1718
tutorials
1819

1920
.. toctree::
@@ -22,6 +23,7 @@ Carbonfly documentation
2223

2324
api
2425

26+
2527
Indices and tables
2628
==================
2729

‎docs/source/installation.rst‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
Installation & Update & Uninstall
2+
=================================
3+
4+
.. contents::
5+
:local:
6+
:depth: 2
7+
8+
.. note::
9+
:class: important
10+
11+
Check out our video tutorial on `How to Install Carbonfly <https://www.youtube.com/watch?v=2cnaCHx_9OI>`_
12+
13+
How to install?
14+
---------------
15+
16+
Step 1: Install WSL
17+
~~~~~~~~~~~~~~~~~~~
18+
19+
In Windows 10 or 11, install WSL 2 with Ubuntu-20.04 (should also work with Ubuntu-22.04, not tested) in a terminal window (e.g. PowerShell), also see `WSL Documentation - How to install Linux on Windows with WSL <https://learn.microsoft.com/en-us/windows/wsl/install>`_:
20+
21+
1. ``wsl --install -d Ubuntu-20.04``
22+
23+
.. image:: ../../pics/install_wsl_01.png
24+
:alt: install wsl Ubuntu-20.04
25+
:width: 100%
26+
27+
2. Open ``Ubuntu 20.04 LTS``, you will see the following console. Please set up your WSL, also see `Set up a WSL development environment <https://learn.microsoft.com/en-us/windows/wsl/setup/environment#set-up-your-linux-username-and-password>`_
28+
29+
.. image:: ../../pics/install_wsl_02.png
30+
:alt: set up wsl Ubuntu-20.04
31+
:width: 100%
32+
33+
3. Once you have finished setting up, you should see the following welcome message:
34+
35+
.. image:: ../../pics/install_wsl_03.png
36+
:alt: finish wsl Ubuntu-20.04
37+
:width: 100%
38+
39+
`Back to top ↥ <#carbonfly-installation--update--uninstall>`_
40+
41+
Step 2: Install OpenFOAM v10
42+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
43+
44+
Install OpenFOAM v10 in WSL - Ubuntu 20.04 LTS (should be able to find it in the Windows menu, with an orange icon), also see `Download v10 | Ubuntu <https://openfoam.org/download/10-ubuntu/>`_:
45+
46+
1. ``sudo sh -c "wget -O - https://dl.openfoam.org/gpg.key > /etc/apt/trusted.gpg.d/openfoam.asc"``
47+
2. ``sudo add-apt-repository http://dl.openfoam.org/ubuntu``
48+
3. ``sudo apt-get update``
49+
4. ``sudo apt-get -y install openfoam10``
50+
51+
.. note::
52+
Tip: Ctrl+V doesn't work in Ubuntu, use right-click to paste
53+
54+
As described in OpenFOAM documentation, complete the following:
55+
56+
5. Find the ``.bashrc`` file in the user's home directory, e.g. using Windows File Explorer: ``Linux/Ubuntu-20.04/home/user/.bashrc`` and open the file using any text editor app e.g. `Notepad 3 <https://github.com/rizonesoft/Notepad3>`_
57+
58+
.. image:: ../../pics/install_openfoam_01.png
59+
:alt: find .bashrc file
60+
:width: 100%
61+
62+
6. At the bottom of that file, add ``source /opt/openfoam10/etc/bashrc`` and save the file.
63+
64+
.. image:: ../../pics/install_openfoam_02.png
65+
:alt: add openfoam in .bashrc file
66+
:width: 100%
67+
68+
7. Restart WSL and test with ``simpleFoam -help`` in a new WSL window:
69+
70+
.. image:: ../../pics/install_openfoam_03.png
71+
:alt: add openfoam in .bashrc file
72+
:width: 100%
73+
74+
`Back to top ↥ <#carbonfly-installation--update--uninstall>`_
75+
76+
Step 3: Install Carbonfly
77+
~~~~~~~~~~~~~~~~~~~~~~~~~
78+
79+
Manual installation
80+
^^^^^^^^^^^^^^^^^^^
81+
82+
1. Download ``.zip`` file (or source code) of latest release from `Releases <https://github.com/RWTH-E3D/carbonfly/releases>`_
83+
2. Unzip the file
84+
3. Copy the ``carbonfly`` folder to the Rhino 8 script path: ``%AppData%\McNeel\Rhinoceros\8.0\scripts``
85+
86+
.. note::
87+
Note: If you have just installed Rhino, the ``scripts`` folder may not yet exist. Please manually create a new ``scripts`` folder at this path ``%AppData%\McNeel\Rhinoceros\8.0``.
88+
89+
.. image:: ../../pics/manual_installation_copy_rhino_8_script.png
90+
:alt: manual installation copy rhino 8 script
91+
:width: 100%
92+
93+
4. Copy the ``Carbonfly`` folder (under ``grasshopper/UserObjects``) to the ``%AppData%\Grasshopper\UserObjects``
94+
95+
.. note::
96+
Note: If you have just installed Rhino, the ``Grasshopper`` folder may not yet exist. Please run Grasshopper in your Rhino first. The folder will be created after the first run.
97+
98+
.. image:: ../../pics/manual_installation_copy_grasshopper_user_objects.png
99+
:alt: manual installation copy grasshopper user objects
100+
:width: 100%
101+
102+
5. Restart Rhino and Grasshopper. You should now see Carbonfly in the tabs:
103+
104+
.. image:: ../../pics/carbonfly_in_grasshopper.png
105+
:alt: manual installation copy grasshopper user objects
106+
:width: 100%
107+
108+
6. To help you get started quickly, we've prepared numerous examples. See `Examples <./examples>`_.
109+
110+
Installer
111+
^^^^^^^^^
112+
113+
Coming soon...
114+
115+
`Back to top ↥ <#carbonfly-installation--update--uninstall>`_
116+
117+
Step 4: Install ParaView (optional)
118+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
119+
120+
Although `ParaView <https://www.paraview.org/>`_ (for post-processing) should be automatically installed in the WSL environment during OpenFOAM v10 installation, it is still recommended to install an additional `ParaView <https://www.paraview.org/>`_ instance in the Windows environment. This allows for more convenient viewing of results and post-processing after simulations.
121+
122+
After simulation, simply double-click the automatically generated ``.foam`` file in the Carbonfly case folder (see `Examples <./examples>`_) to open ParaView and view simulation results for post-processing:
123+
124+
.. image:: ../../pics/post_processing_paraview_01.png
125+
:alt: open results in paraview
126+
:width: 100%
127+
128+
.. image:: ../../pics/post_processing_paraview_02.png
129+
:alt: post processing in paraview
130+
:width: 100%
131+
132+
`Back to top ↥ <#carbonfly-installation--update--uninstall>`_
133+
134+
How to update Carbonfly?
135+
------------------------
136+
137+
1. Close Rhino and Grasshopper.
138+
2. Download the latest ``.zip`` from `Releases <https://github.com/RWTH-E3D/carbonfly/releases>`_.
139+
3. Replace the old folders with the new ones:
140+
- Delete ``%AppData%\McNeel\Rhinoceros\8.0\scripts\carbonfly`` and copy in the new ``carbonfly`` folder.
141+
- Delete ``%AppData%\Grasshopper\UserObjects\Carbonfly`` and copy in the new ``Carbonfly`` folder from ``grasshopper/UserObjects``.
142+
143+
How to uninstall Carbonfly?
144+
---------------------------
145+
146+
1. Close Rhino and Grasshopper.
147+
2. Delete the ``carbonfly`` folder from the Rhino 8 script path: ``%AppData%\McNeel\Rhinoceros\8.0\scripts``.
148+
3. Delete the ``Carbonfly`` folder from the Grasshopper plugin path: ``%AppData%\Grasshopper\UserObjects``.
149+
4. (Optional) Uninstall the Linux distribution you installed like ``Ubuntu 20.04 LTS`` from the "Apps & features" or "Installed apps" settings in Windows.
150+
151+
.. note::
152+
In Windows Terminal, you can use the command ``wsl -l`` to check all installed Linux distributions.

‎docs/source/introduction.rst‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
1-
This documentation provides an overview of the **Carbonfly** Python library,
2-
including its purpose, design principles, and typical use cases.
1+
This documentation provides an overview of the **Carbonfly** Python library.
32

43
For documentation of the **Carbonfly** Grasshopper toolbox, please see: https://github.com/RWTH-E3D/carbonfly/tree/master/documentation
54

0 commit comments

Comments
 (0)