checkpoint

Author: TheAssembler1

docs/source/advanced_topics.rst

@@ -8,19 +8,20 @@ It includes the types, core layer functions, properties, containers,
 objects, and region management functions. Use the links below to 
 quickly navigate to each subsection:
 
-- :ref:`client_api_types` - Types used in the Client API
-- :ref:`client_api_layer` - Initialization and shutdown functions for the PDC layer
-- :ref:`client_api_properties` - Functions for creating and closing properties
-- :ref:`client_api_containers` - Functions for creating and managing containers
-- :ref:`client_api_objects` - Functions for creating and managing objects
-- :ref:`client_api_object_tags` - Functions for creating and managing object tags
-- :ref:`client_api_regions` - Functions for creating and managing regions
-- :ref:`client_api_object_data_transfers` - Functions for object data transfers
-
-.. _client_api_types:
-
-**4.1.** Types
---------------
+- :ref:`client_api_data_types` - Data types used in the Client API.
+- :ref:`client_api_layer` - Initialization and shutdown functions for the PDC layer.
+- :ref:`client_api_properties` - Functions for creating and closing properties.
+- :ref:`client_api_containers` - Functions for creating and managing containers.
+- :ref:`client_api_objects` - Functions for creating and managing objects.
+- :ref:`client_api_object_tags` - Functions for creating and managing object tags.
+- :ref:`client_api_regions` - Functions for creating and managing regions.
+- :ref:`client_api_object_data_transfers` - Functions for object data transfers.
+- :ref:`client_api_object_data_querying` - Functions for querying object data.
+
+.. _client_api_data_types:
+
+**4.1.** Data Types
+-------------------
 
 .. doxygentypedef:: pdcid_t
    :project: PDC
@@ -40,10 +41,28 @@ quickly navigate to each subsection:
 .. doxygenenum:: pdc_lifetime_t
    :project: PDC
 
-.. doxygenenum:: pdc_prop_type_t
+.. doxygenenum:: pdc_consistency_t
    :project: PDC
 
-.. doxygenenum:: pdc_consistency_t
+.. doxygenenum:: pdc_prop_name_t
+   :project: PDC
+
+.. doxygenenum:: pdc_query_op_t
+   :project: PDC
+
+.. doxygenenum:: pdc_query_combine_op_t
+   :project: PDC
+
+.. doxygenenum:: pdc_query_get_op_t
+   :project: PDC
+
+.. doxygentypedef:: pdc_selection_t
+   :project: PDC
+
+.. doxygentypedef:: pdc_query_constraint_t
+   :project: PDC
+
+.. doxygentypedef:: pdc_query_t
    :project: PDC
 
 .. _client_api_layer:
@@ -198,4 +217,48 @@ quickly navigate to each subsection:
    :project: PDC
 
 .. doxygenfunction:: PDCobj_get_data
+   :project: PDC
+
+.. _client_api_object_data_querying:
+
+**4.9** Object Data Querying
+----------------------------
+
+.. doxygenfunction:: PDCquery_create
+   :project: PDC
+
+.. doxygenfunction:: PDCquery_and
+   :project: PDC
+
+.. doxygenfunction:: PDCquery_or
+   :project: PDC
+
+.. doxygenfunction:: PDCquery_sel_region
+   :project: PDC
+
+.. doxygenfunction:: PDCquery_get_selection
+   :project: PDC
+
+.. doxygenfunction:: PDCquery_get_data
+   :project: PDC
+
+.. doxygenfunction:: PDCquery_get_histogram
+   :project: PDC
+
+.. doxygenfunction:: PDCselection_free
+   :project: PDC
+
+.. doxygenfunction:: PDCquery_free
+   :project: PDC
+
+.. doxygenfunction:: PDCquery_free_all
+   :project: PDC
+
+.. doxygenfunction:: PDCquery_print
+   :project: PDC
+
+.. doxygenfunction:: PDCselection_print
+   :project: PDC
+
+.. doxygenfunction:: PDCselection_print_all
    :project: PDC

docs/source/appendix.rst

@@ -80,9 +80,7 @@ Regions
 -------------------
 
 Properties determine how objects, containers, etc., behave. 
-A property list is created using ``PDCprop_create(x)``, where ``x`` is 
-the entity type (``PDC_CONTAINER``, ``PDC_OBJ``, etc.). Once created, the 
-property list can be configured through additional function calls that 
+Once created, the property list can be configured through additional function calls that 
 append or modify properties. These customized property lists can then be 
 used in later calls to control the behavior of the associated entities. Some 
 examples of configurable properties are shown below.

docs/source/client_api.rst

@@ -26,19 +26,17 @@ Use the table of contents below to explore the sections in more detail
    introduction
    core_concepts
    using_pdc
-.. advanced_topics
 
 .. toctree::
    :maxdepth: 2
    :caption: Client API/Tools & Develop Guide
 
    client_api
    client_tools
-.. developer_guide
 
 .. toctree::
    :maxdepth: 1
    :caption: Community and Contributions
 
    contributing
-.. appendix
+   roadmap

docs/source/core_concepts.rst

@@ -35,14 +35,13 @@ PDC offers the following methods for installing core dependencies:
 
 PDC offers the following installation targets:
 
-1. :ref:`C API <c-api>`
+1. `C API`
 2. :ref:`Python API (PDCpy) <python-api-pdc-py>`
 3. :ref:`HDF5 VOL Connector (VOL-PDC) <hdf5-vol-connector>`
 
 .. figure:: ../_static/image/pdc-installation.png
    :alt: PDC Installation Diagram
    :align: center
-   :class: bordered-image
 
    Installation workflow to install the client targets offered by PDC.
 
@@ -353,6 +352,22 @@ Legend:
 - 🟡 = Partially/experimentally supported
 - 🔴 = Not supported or currently disabled
 
+Several parameters can be specified at compile-time
+and then subsequently overwritten at runtime by
+setting the appropriate environment variable.
+
+Runtime Options
+~~~~~~~~~~~~~~~
+
+- PDC_DATA_LOC: Data directory path.
+- PDC_TMPDIR: Metadata directory path.
+- PDC_BB_LOC: Burst buffer directory path.
+- PDC_SERVER_CACHE_MAX_SIZE: Max server side cache size (GB).
+- PDC_SERVER_IDLE_CACHE_FLUSH_TIME: Time interval of the server side cache inactivity before automatic flush (sec).
+- PDC_SERVER_CACHE_NO_FLUSH: Disable the flushing of the server side cache.
+- HG_TRANSPORT: Specifies the Mercury communication transport protocol.
+- HG_HOST: Defines the hostname or IP address used by the Mercury network layer.
+
 .. note::
 
    ``-DCMAKE_C_COMPILER=mpicc -DMPI_RUN_CMD=mpiexec`` may need to be 
@@ -398,11 +413,6 @@ using the ``-L serial`` parameter:
    on a compute node, you can submit an interactive job on Perlmutter: 
    ``salloc --nodes 1 --qos interactive --time 01:00:00 --constraint cpu --account=mxxxx``
 
-.. _c-api:
-
-**1.3.** C API
---------------
-
 .. _python-api-pdc-py:
 
 **1.4.** Python API (PDCpy)
@@ -756,4 +766,14 @@ No Provider Found
 Mercury was unable to find a valid provider based on your hostname (``ta1-pc`` in this case).
 Please review the connection string (``ofi+tcp://ta1-pc:7000``) and ensure that the appropriate
 transport and host are set. If you're unsure which transport or host to use, you can run ``fi_info``
-(found in the ``bin`` directory of your libfabric installation) to list available network providers.
+(found in the ``bin`` directory of your libfabric installation) to list available network providers.
+
+
+**1.9.** Contact and Additional Information
+-------------------------------------------
+
+For questions, collaborations, or feedback, please open an issue on the project's GitHub page.  
+You can also explore the **PDC Dashboard** for an evaluation of **VPIC**, a particle simulation I/O kernel.
+
+- **Project Page:** `https://github.com/hpc-io/pdc <https://github.com/hpc-io/pdc>`_
+- **PDC Dashboard:** `Google Sheets Link <https://docs.google.com/spreadsheets/d/1Ho5W4U56lT03OHS5AVFhn9hT6eJIfBj-sCa20F--3VY/edit?gid=1616818039#gid=1616818039>`_

docs/source/developer_guide.rst

@@ -0,0 +1,51 @@
+**7.** PDC Project Roadmap
+===========================
+
+**7.1.** Overview
+-----------------
+
+This roadmap outlines the current focus areas, near-term development goals, and long-term
+vision for PDC.
+
+**7.2.** Current Focus (Ongoing)
+--------------------------------
+
+- **Stability and Performance**
+  - Continue improving metadata and data transfer scalability across large-scale HPC systems.
+  - Optimize communication via Mercury and MPI layers.
+  - Enhance fault tolerance and recovery mechanisms for PDC servers.
+
+- **User Experience**
+  - Streamline configuration with clearer environment variables and default parameters.
+  - Expand documentation and example workflows for common HPC use cases.
+
+- **Interoperability**
+  - Strengthen integration with HDF5, ADIOS, and other I/O frameworks.
+  - Improve support for various network transports through Mercury (``ofi``, ``tcp``, ``verbs``, etc.).
+
+**7.3.** Short-Term Goals (Next 6-12 Months)
+--------------------------------------------
+
+- Implement enhanced **data caching and eviction policies** to reduce I/O latency.
+- Improve **burst buffer management** for hybrid memory/storage architectures.
+- Extend **metadata indexing** and search capabilities.
+- Add more comprehensive **unit and integration tests** in CI pipelines.
+- Expand **PDC client APIs** in C and Python with better documentation and examples.
+
+**7.4.** Medium-Term Goals (1-2 Years)
+--------------------------------------
+
+- Introduce **multi-tier data management** (memory, SSD, disk, object storage).
+- Develop **asynchronous data movement and prefetching** mechanisms.
+- Enhance **seurity and authentication** (e.g., Cray DRC, token-based access).
+- Support **federated PDC deployments** across distributed sites.
+
+**7.5.** Long-Term Vision (Beyond 2 Years)
+------------------------------------------
+
+- Enable **self-optimizing data placement** based on access patterns and system telemetry.
+- Integrate with **workflow and data provenance frameworks** for end-to-end data lifecycle management.
+- Expand **AI-driven data management features**, such as automated cache tuning and prediction-based prefetching.
+- Achieve production-grade stability and adoption across DOE and large HPC facilities.
+
+*Last updated: November 2025*