Update documentation

daniloceano · Sep 5, 2024 · 4b10f45 · 4b10f45
commit 4b10f45
Show file tree

Hide file tree

Showing 44 changed files with 5,785 additions and 0 deletions.
diff --git a/.buildinfo b/.buildinfo
@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 99a8daa41ea9da53d336bc39498639e8
+tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/.nojekyll b/.nojekyll
diff --git a/_sources/configuration.rst.txt b/_sources/configuration.rst.txt
@@ -0,0 +1,47 @@
+Configuration
+=============
+
+The LorenzCycleToolkit requires specific configuration files for both fixed and moving frameworks. Below are examples and descriptions of the required configuration files.
+
+Namelist File
+-------------
+
+The `namelist` file specifies the variable names and units used in the input NetCDF file. Here is an example `namelist` file for the NCEP-R2 dataset:
+
+.. code-block:: text
+
+    ;standard_name;Variable;Units
+    Air Temperature;air_temperature;TMP_2_ISBL;K
+    Geopotential Height;geopotential_height;HGT_2_ISBL;m
+    Omega Velocity;omega;V_VEL_2_ISBL;Pa/s
+    Eastward Wind Component;eastward_wind;U_GRD_2_ISBL;m/s
+    Northward Wind Component;northward_wind;V_GRD_2_ISBL;m/s
+    Longitude;;lon_2
+    Latitude;;lat_2
+    Time;;initial_time0_hours
+    Vertical Level;;lv_ISBL3
+
+Box Limits File (Optional)
+--------------------------
+
+The `box_limits` file defines the spatial domain for the fixed framework. It is a CSV file with the following format:
+
+.. code-block:: text
+
+    min_lon;-60
+    max_lon;-30
+    min_lat;-42.5
+    max_lat;-17.5
+
+Track File (Optional)
+---------------------
+
+For the moving framework, a `track_file` can be used to define the system's center over time. Optionally, length and width columns can be added to adjust the domain size. Here is an example `track_file`:
+
+.. code-block:: text
+
+    time, lon, lat, length, width
+    2021-01-01 00:00:00, -50, 0, 10, 10
+    2021-01-01 06:00:00, -49, 1, 10, 10
+    2021-01-01 12:00:00, -48, 2, 10, 10
+
diff --git a/_sources/contributing.rst.txt b/_sources/contributing.rst.txt
@@ -0,0 +1,40 @@
+Contributing
+============
+
+We welcome contributions to improve LorenzCycleToolkit! Please follow these steps to contribute:
+
+1. **Fork the repository** and clone your fork.
+2. **Create a new branch**: 
+   - Use one of the following naming conventions:
+     - ``feature/your-feature-name`` for new features
+     - ``bugfix/your-bug-name`` for bug fixes
+     - ``hotfix/your-hotfix-name`` for urgent fixes
+   - Example: ``git checkout -b feature/new-visualization``
+3. **Make your changes** following the project's coding standards.
+4. **Test your changes**: Ensure all tests pass by running:
+   .. code-block:: bash
+
+      pytest
+     
+5. **Format your code**: Run the following commands to ensure your code adheres to the project standards:
+   .. code-block:: bash
+
+      autopep8 --in-place --recursive .
+      isort .
+      flake8
+
+6. **Commit your changes**: 
+   - Use descriptive commit messages, e.g., ``git commit -m 'Add energy cycle visualization feature'``
+7. **Push your changes** to your fork:
+   .. code-block:: bash
+
+      git push origin feature/new-visualization
+      
+8. **Create a pull request**: Submit your PR through GitHub, following our PR template and referencing any related issues.
+
+Before submitting your pull request, please ensure:
+
+- Your code passes all tests and follows the coding standards.
+- You have added or updated documentation if necessary.
+
+Thank you for contributing!
diff --git a/_sources/examples_and_tutorials.rst.txt b/_sources/examples_and_tutorials.rst.txt
@@ -0,0 +1,80 @@
+Examples and Tutorials
+======================
+
+The preferred method for using the LorenzCycleToolkit is through command line arguments executed from the top-level directory of the project. Below are examples demonstrating how to configure and run the toolkit using different frameworks.
+
+Fixed (Eulerian) Framework Example
+----------------------------------
+1. Prepare the `inputs/box_limits` file.  
+   The `box_limits` file should define the spatial domain as a CSV file with the following format:
+
+   .. code-block:: text
+
+       min_lon;-60
+       max_lon;-30
+       min_lat;-42.5
+       max_lat;-17.5
+
+2. Prepare the `inputs/namelist` file.  
+   The `namelist` file specifies the variable names and units used in the input NetCDF file. Here is an example for the National Center for Environmental Protection Reanalysis 2 (NCEP-R2) dataset:
+
+   .. code-block:: text
+
+       ;standard_name;Variable;Units
+       Air Temperature;air_temperature;TMP_2_ISBL;K
+       Geopotential Height;geopotential_height;HGT_2_ISBL;m
+       Omega Velocity;omega;V_VEL_2_ISBL;Pa/s
+       Eastward Wind Component;eastward_wind;U_GRD_2_ISBL;m/s
+       Northward Wind Component;northward_wind;V_GRD_2_ISBL;m/s
+       Longitude;;lon_2
+       Latitude;;lat_2
+       Time;;initial_time0_hours
+       Vertical Level;;lv_ISBL3
+
+3. From the top-level directory of the project, run the following command::
+
+       python lorenzcycletoolkit.py samples/testdata_NCEP-R2.nc -r -f
+
+   This will execute the LorenzCycleToolkit using the fixed (Eulerian) framework.
+
+Moving (Semi-Lagrangian) Framework Example  
+------------------------------------------
+
+1. Prepare the `inputs/track_file`.  
+   The `track_file` should define the system's center over time. Optionally, add length and width columns to adjust the domain size. Example:
+
+   .. code-block:: text
+
+       time;Lat;Lon
+       2005-08-08-0000;-22.5;-45.0
+       2005-08-08-0600;-22.6;-44.9
+       2005-08-08-1200;-22.7;-44.8
+       2005-08-08-1800;-22.8;-44.7
+       2005-08-09-0000;-22.9;-44.6
+
+   A default track file for testing purposes is also provided and can be used by running the following command:
+
+   .. code-block:: shell
+
+       cp inputs/track_testdata_NCEP-R2 inputs/track
+
+   The program will always use the `inputs/track` file for processing. Therefore, if you have a custom track file, you need to overwrite the `inputs/track` file with the desired track data before running the program.
+
+2. From the top-level directory of the project, run the following command::
+
+       python lorenzcycletoolkit.py samples/testdata__NCEP-R2.nc -r -t
+
+   This will execute the LorenzCycleToolkit using the moving (Semi-Lagrangian) framework.
+
+Interactive Domain Selection Example
+------------------------------------
+1. From the top-level directory of the project, run the following command::
+
+       python lorenzcycletoolkit.py samples/testdata__NCEP-R2.nc -r -c
+
+   This command enables interactive map-based domain selection. First, define a slice of global data to enhance visualization and processing speed. Then, select the computational area for each timestep interactively.
+
+   Each timestep prompts the user to select a computational area:
+
+   .. image:: https://user-images.githubusercontent.com/56005607/214922008-5b7c094f-c160-4415-a528-07cc58730827.png
+      :width: 350
diff --git a/_sources/file_naming_convention.rst.txt b/_sources/file_naming_convention.rst.txt
@@ -0,0 +1,4 @@
+File Naming Convention
+======================
+
+Use a naming convention like "subject_source.nc" for input files. For compound names, use a hyphen, e.g., "Cyclone-20100101_NCEP-R2.nc".
diff --git a/_sources/index.rst.txt b/_sources/index.rst.txt
@@ -0,0 +1,26 @@
+.. LorenzCycleToolKit documentation master file, created by
+   sphinx-quickstart on Tue Jul 16 08:16:48 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+LorenzCycleToolkit
+==================
+
+Welcome to the LorenzCycleToolkit documentation! This toolkit is designed to calculate the Lorenz Energy Cycle (LEC) for specific atmospheric regions.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   overview
+   installation
+   usage
+   configuration
+   file_naming_convention
+   examples_and_tutorials
+   results
+   math
+   contributing
+   support
+   license
+   references
diff --git a/_sources/installation.rst.txt b/_sources/installation.rst.txt
@@ -0,0 +1,43 @@
+Installation
+============
+
+Prerequisites
+-------------
+- Python 3.12 or later
+
+Steps
+-----
+
+1. Install via pip::
+
+   pip install LorenzCycleToolkit
+
+2. Alternatively, clone the repository::
+
+   git clone https://github.com/daniloceano/lorenz-cycle.git
+   cd lorenz-cycle
+
+3. Create a virtual environment and activate it::
+
+   python -m venv venv
+   source venv/bin/activate
+
+4. Install the dependencies::
+
+   pip install -r requirements.txt
+
+For Conda users:
+
+1. Clone the repository::
+
+   git clone https://github.com/daniloceano/lorenz-cycle.git
+   cd lorenz-cycle
+
+2. Create a Conda environment and activate it::
+
+   conda create --name lorenzcycletoolkit python=3.12
+   conda activate lorenzcycletoolkit
+
+3. Install the dependencies::
+
+   pip install -r requirements.txt
diff --git a/_sources/license.rst.txt b/_sources/license.rst.txt
@@ -0,0 +1,4 @@
+License
+=======
+
+This project is licensed under the GNU License Version 3 - see the `LICENSE <../LICENSE>`_ file for details.