Readme installation

README.md

@@ -50,9 +50,100 @@
   * Fragility Functions
   * Vulnerability Functions
 
+# 👩‍💻🧑‍💻 Installation
+
+Follow these steps to install the required tools and set up the development environment. Note that this procedure implies the installation of the OpenQuake engine dependencies. This procedure was tested on Windows and Linux OS.
+It is highly recommended to use a **virtual environment** to install this tool. A virtual environment is an isolated Python environment that allows you to manage dependencies for this project separately from your system’s Python installation. This ensures that the required dependencies for the OpenQuake engine do not interfere with other Python projects or system packages, which could lead to version conflicts.
+
+1. Open a terminal and navigate to the folder where you intend to install the virtual environment using the "cd" command.
+
+  ```bash
+   cd <virtual_environment_directory>
+  ```
+
+2. Create a virtual environment using the following command:
+
+  ```bash
+   python3 -m venv <virtual_environment_name>
+  ```
+
+3. Activate the virtual environment:
+* On Linux:
+
+  ```bash
+   source <virtual_environment_directory>/bin/activate
+  ```
+
+* On Windows:
+
+  ```bash
+   <virtual_environment_directory>\Scripts\Activate.ps1
+  ```
+
+4. Enter (while on virtual environment) the preferred directory for "oq-vmtk" using the "cd" command
+
+  ```bash
+   cd <preferred_directory>
+  ```
+
+5. Clone the "oq-vmtk" repository
+
+ ```bash
+ git clone https://github.com/GEMScienceTools/oq-vmtk.git
+ ```
+
+6. Complete the development installation by running the following commands depending on your python version {py-version} (e.g., 310, 311 or 312):
+* On Linux
+
+  ```bash
+  pip install -r requirements-py-linux.txt
+  pip install -e .
+  ```
+
+* On Windows
+
+  ```bash
+  pip install -r requirements-py-win64.txt
+  pip install -e .
+  ```
+
 # 📚 Documentation
 
-TBD
+[WIP]
+
+# 📼 Demos
+
+The repository includes demo scripts that showcase the functionality of the vulnerability-modellers-toolkit (oq-vmtk). You can find them in the demos folder of the repository.
+
+To run a demo, simply navigate to the demos directory and execute the relevant demo script in Jupyter Lab. Jupyter Lab is automatically installed with oq-vmtk.
+
+1. Open a terminal and activate the virtual environment:
+* On Linux:
+
+  ```bash
+   source <virtual_environment_directory>/bin/activate
+  ```
+
+* On Windows:
+
+  ```bash
+   <virtual_environment_directory>\Scripts\Activate.ps1
+  ```
+
+* To deactivate virtual environment:
+
+  ```bash
+   deactivate
+  ```
+
+2. Open Jupyter Lab from the terminal:
+
+  ```bash
+   jupyter-lab
+  ```
+
+3. Navigate to the "demos" folder
+4. Run the examples
 
 # 🌟 Contributors
 
@@ -74,17 +165,11 @@ This work is licensed under an AGPL v3 license (https://www.gnu.org/licenses/agp
 
 ### How to contribute?
 
-You can follow the instructions indicated in the [contributing guidelines](./contribute_guidelines.md). (Work-In-Progress)
-
-### Which version am I seeing? How to change the version?
-
-By default, you will see the files in the repository in the `main` branch. Each version of the model that is released can be accessed is marked with a `tag`. By changing the tag version at the top of the repository, you can change see the files for a given version.
-
-Note that the `main` branch could contain the work-in-progress of the next version of the model.
+You can follow the instructions indicated in the [contributing guidelines](./contribute_guidelines.md)
 
 # 📑 References
 
-TBD
+[WIP]
 
 <!-- MARKDOWN LINKS & IMAGES -->
 <!-- https://www.markdownguide.org/basic-syntax/#reference-style-links -->

contribute_guidelines.md

@@ -1,7 +1,12 @@
 # 🤓 CONTRIBUTE TO THE VULNERABILITY TOOLKIT
 
-You can contribute by improving the code available, addressing issues and bugs or include additional functionalities.
+We welcome contributions to improve the vulnerability-modellers-toolkit (oq-vmtk) and this repository! If you'd like to contribute, follow the steps below. Otherwise, you can email your information to [email protected]_.
 
-If you are familiar working with `git` repositories, open a pull request with the new information, and follow the standards and recommendations in the sections below. Otherwise, you can email your information to [email protected]_.
+1. Fork the repository on GitHub.
+2. Clone your fork to your local machine.
+3. Create a new branch for your feature or fix (git checkout -b feature-branch).
+4. Make your changes and commit them (git commit -am 'Add new feature').
+5. Push your changes to your fork (git push origin feature-branch).
+6. Open a pull request on GitHub.
 
-Contribution guidelines to be available soon.
+Please ensure that your code follows the existing style and includes relevant tests and documentation.

demos/example_1.ipynb

@@ -46,10 +46,22 @@
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 1,
    "id": "3aa0f9f2-68c4-4201-b9ef-5d90031e4477",
    "metadata": {},
-   "outputs": [],
+   "outputs": [
+    {
+     "ename": "ModuleNotFoundError",
+     "evalue": "No module named 'openquake.vmtk'",
+     "output_type": "error",
+     "traceback": [
+      "\u001b[31m---------------------------------------------------------------------------\u001b[39m",
+      "\u001b[31mModuleNotFoundError\u001b[39m                       Traceback (most recent call last)",
+      "\u001b[36mCell\u001b[39m\u001b[36m \u001b[39m\u001b[32mIn[1]\u001b[39m\u001b[32m, line 8\u001b[39m\n\u001b[32m      5\u001b[39m \u001b[38;5;28;01mimport\u001b[39;00m\u001b[38;5;250m \u001b[39m\u001b[34;01mmatplotlib\u001b[39;00m\u001b[34;01m.\u001b[39;00m\u001b[34;01mpyplot\u001b[39;00m\u001b[38;5;250m \u001b[39m\u001b[38;5;28;01mas\u001b[39;00m\u001b[38;5;250m \u001b[39m\u001b[34;01mplt\u001b[39;00m\n\u001b[32m      7\u001b[39m \u001b[38;5;66;03m# Import the IMCalculator class\u001b[39;00m\n\u001b[32m----> \u001b[39m\u001b[32m8\u001b[39m \u001b[38;5;28;01mfrom\u001b[39;00m\u001b[38;5;250m \u001b[39m\u001b[34;01mopenquake\u001b[39;00m\u001b[34;01m.\u001b[39;00m\u001b[34;01mvmtk\u001b[39;00m\u001b[34;01m.\u001b[39;00m\u001b[34;01mim_calculator\u001b[39;00m\u001b[38;5;250m \u001b[39m\u001b[38;5;28;01mimport\u001b[39;00m IMCalculator \n\u001b[32m      9\u001b[39m \u001b[38;5;28;01mfrom\u001b[39;00m\u001b[38;5;250m \u001b[39m\u001b[34;01mopenquake\u001b[39;00m\u001b[34;01m.\u001b[39;00m\u001b[34;01mvmtk\u001b[39;00m\u001b[34;01m.\u001b[39;00m\u001b[34;01mutilities\u001b[39;00m\u001b[38;5;250m     \u001b[39m\u001b[38;5;28;01mimport\u001b[39;00m sorted_alphanumeric, export_to_pkl\n",
+      "\u001b[31mModuleNotFoundError\u001b[39m: No module named 'openquake.vmtk'"
+     ]
+    }
+   ],
    "source": [
     "import os\n",
     "import sys\n",

demos/example_2.ipynb

@@ -313,7 +313,7 @@
     "                                                                                                                                                                                                          sf, \n",
     "                                                                                                                                                                                                          t_max, \n",
     "                                                                                                                                                                                                          dt_ansys,\n",
-    "                                                                                                                                                                                                          temp_nrha_outdir,\n",
+    "                                                                                                                                                                                                          temp_nrha_directory,\n",
     "                                                                                                                                                                                                          pflag=False,\n",
     "                                                                                                                                                                                                          xi = mdof_damping)\n",
     "\n",
@@ -363,6 +363,14 @@
     "# Export the analysis output variable to a pickle file using the \"export_to_pkl\" function from \"utilities\"\n",
     "export_to_pkl(os.path.join(nrha_directory,'ansys_out.pkl'), ansys_dict) "
    ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "6d41ae04-db7a-4d79-b7d9-bfc4aff65bdd",
+   "metadata": {},
+   "outputs": [],
+   "source": []
   }
  ],
  "metadata": {

requirements-py310-win64.txt

@@ -1,13 +1,13 @@
 # vmtk requirements
 # From OQ wheels
 #
-https://wheelhouse.openquake.org/v3/windows/py311/pandas-2.0.3-cp311-cp311-win_amd64.whl
-https://wheelhouse.openquake.org/v3/windows/py311/numpy-1.26.2-cp311-cp311-win_amd64.whl
-https://wheelhouse.openquake.org/v3/windows/py311/matplotlib-3.8.2-cp311-cp311-win_amd64.whl
-https://wheelhouse.openquake.org/v3/windows/py311/scipy-1.11.4-cp311-cp311-win_amd64.whl
-https://wheelhouse.openquake.org/v3/windows/py311/fiona-1.9.5-cp311-cp311-win_amd64.whl
-https://wheelhouse.openquake.org/v3/windows/py311/GDAL-3.7.3-cp311-cp311-win_amd64.whl
-https://wheelhouse.openquake.org/v3/windows/py311/pyproj-3.6.1-cp311-cp311-win_amd64.whl
+https://wheelhouse.openquake.org/v3/windows/py310/pandas-2.0.3-cp310-cp310-win_amd64.whl
+https://wheelhouse.openquake.org/v3/windows/py310/fiona-1.9.5-cp310-cp310-win_amd64.whl
+https://wheelhouse.openquake.org/v3/windows/py310/GDAL-3.7.3-cp310-cp310-win_amd64.whl
+https://wheelhouse.openquake.org/v3/windows/py310/pyproj-3.6.1-cp310-cp310-win_amd64.whl
+https://wheelhouse.openquake.org/v3/windows/py310/scipy-1.11.4-cp310-cp310-win_amd64.whl
+https://wheelhouse.openquake.org/v3/windows/py310/numpy-1.26.2-cp310-cp310-win_amd64.whl
+https://wheelhouse.openquake.org/v3/windows/py310/matplotlib-3.8.2-cp310-cp310-win_amd64.whl
 https://wheelhouse.openquake.org/v3/windows/py310/h5py-3.10.0-cp310-cp310-win_amd64.whl
 https://wheelhouse.openquake.org/v3/windows/py310/numba-0.58.1-cp310-cp310-win_amd64.whl
 https://wheelhouse.openquake.org/v3/windows/py310/llvmlite-0.41.1-cp310-cp310-win_amd64.whl