Documentation update - Assembly fields #1440

Rohit-Kakodkar · 2025-12-02T18:04:12Z

Description

Please describe the changes/features in this pull request.

Adds documentation for assembly fields

Issue Number

If there is an issue created for these changes, link it here

Checklist

Please make sure to check developer documentation on specfem docs.

I ran the code through pre-commit to check style
THE DOCUMENTATION BUILDS WITHOUT WARNINGS/ERRORS
I have added labels to the PR (see right hand side of the PR page)
My code passes all the integration tests
I have added sufficient unittests to test my changes
I have added/updated documentation for the changes I am proposing
I have updated CMakeLists to ensure my code builds
My code builds across all platforms

Adds documentation for assembly fields

core/specfem/assembly/fields/data_access/add_on_device.hpp

core/specfem/assembly/fields/data_access/atomic_add_on_device.hpp

core/specfem/assembly/fields/data_access/load_on_device.hpp

Co-authored-by: Congyue Cui <[email protected]>

Copilot

Pull request overview

This PR adds comprehensive Doxygen documentation for the assembly fields module in SPECFEM++, including detailed descriptions for field storage classes, simulation field containers, and data access functions.

Key changes:

Added complete documentation for field_impl, base_field, and field management classes
Enhanced RST documentation structure with new files for implementation details
Added usage examples and detailed parameter descriptions for all data access functions (load, store, add operations)

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
`docs/sections/api/specfem/assembly/fields/fields.rst`	Updated RST structure to include dimension-specific implementations and corrected doxygen group reference
`docs/sections/api/specfem/assembly/fields/field_impl.rst`	New documentation file for field implementation details
`docs/sections/api/specfem/assembly/fields/base_field.rst`	New documentation file for base field class
`core/specfem/assembly/fields/impl/field_impl.hpp`	Added comprehensive class and method documentation for field implementation
`core/specfem/assembly/fields/fields.hpp`	Enhanced documentation for the main fields container with usage examples
`core/specfem/assembly/fields/dim3/simulation_field.hpp`	Added detailed 3D simulation field documentation
`core/specfem/assembly/fields/dim2/simulation_field.hpp`	Added detailed 2D simulation field documentation
`core/specfem/assembly/fields/data_access/store_on_host.hpp`	Expanded documentation with usage examples for host-side storage
`core/specfem/assembly/fields/data_access/store_on_device.hpp`	Expanded documentation with usage examples for device-side storage
`core/specfem/assembly/fields/data_access/load_on_host.hpp`	Expanded documentation with usage examples for host-side loading
`core/specfem/assembly/fields/data_access/load_on_device.hpp`	Expanded documentation with usage examples for device-side loading
`core/specfem/assembly/fields/data_access/atomic_add_on_device.hpp`	Enhanced atomic operation documentation with usage examples
`core/specfem/assembly/fields/data_access/add_on_device.hpp`	Added defgroup definition and improved documentation with examples
`core/specfem/assembly/fields.hpp`	Added brief documentation for simulation_field forward declaration

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-12-04T18:56:05Z

core/specfem/assembly/fields/data_access/store_on_device.hpp

+ * displacement(0) = computed_disp_x;
+ * displacement(1) = computed_disp_z;
+ * velocity(0) = computed_vel_x;


In the code example, the variable name displacement is used but the accessor is named disp. The example should be consistent: either use disp(0) = ... or rename the accessor variable to displacement.

Suggested change

* displacement(0) = computed_disp_x;

* displacement(1) = computed_disp_z;

* velocity(0) = computed_vel_x;

* disp(0) = computed_disp_x;

* disp(1) = computed_disp_z;

* vel(0) = computed_vel_x;

Copilot · 2025-12-04T18:56:05Z

core/specfem/assembly/fields/data_access/load_on_device.hpp

+ * auto disp_x = displacement(0);
+ * auto disp_z = displacement(1);


In the code example, the variable name displacement is used to access values but the accessor is named disp. The example should be consistent: use disp(0) instead of displacement(0).

Suggested change

* auto disp_x = displacement(0);

* auto disp_z = displacement(1);

* auto disp_x = disp(0);

* auto disp_z = disp(1);

Copilot · 2025-12-04T18:56:06Z

core/specfem/assembly/fields/data_access/atomic_add_on_device.hpp

+ * displacement(0) += delta_disp_x;
+ * displacement(1) += delta_disp_z;


In the code example, the variable name displacement is used to set values but the accessor is named disp. The example should be consistent: use disp(0) += ... instead of displacement(0) += ....

Suggested change

* displacement(0) += delta_disp_x;

* displacement(1) += delta_disp_z;

* disp(0) += delta_disp_x;

* disp(1) += delta_disp_z;

Copilot · 2025-12-04T18:56:06Z

core/specfem/assembly/fields/data_access/add_on_device.hpp

+ * displacement(0) += delta_disp_x;
+ * displacement(1) += delta_disp_z;


In the code example, the variable name displacement is used to update values but the accessor is named disp. The example should be consistent: use disp(0) += ... instead of displacement(0) += ....

Suggested change

* displacement(0) += delta_disp_x;

* displacement(1) += delta_disp_z;

* disp(0) += delta_disp_x;

* disp(1) += delta_disp_z;

Copilot · 2025-12-04T18:56:06Z

core/specfem/assembly/fields/dim2/simulation_field.hpp

+   * auto elastic_field =
+   * field.get_field<specfem::element::medium_tag::elastic_psv>(); auto
+   * displacement = elastic_field.displacement;


In the code example, the variable name displacement is used to access field values but the accessor variable is named elastic_field. The example should use elastic_field.get_field() or similar to properly demonstrate field access.

Suggested change

* auto elastic_field =

* field.get_field<specfem::element::medium_tag::elastic_psv>(); auto

* displacement = elastic_field.displacement;

* auto elastic_field = field.get_field<specfem::element::medium_tag::elastic_psv>();

* auto displacement = elastic_field.displacement;

* // Now you can use displacement for further computations

Copilot · 2025-12-04T18:56:07Z

core/specfem/assembly/fields/data_access/load_on_host.hpp

+ * std::cout << "Displacement X: " << displacement(0) << std::endl;
+ * std::cout << "Displacement Z: " << displacement(1) << std::endl;


In the code example, the variable name displacement is used in the std::cout statement but the accessor is named disp. The example should be consistent: use disp(0) instead of displacement(0).

Suggested change

* std::cout << "Displacement X: " << displacement(0) << std::endl;

* std::cout << "Displacement Z: " << displacement(1) << std::endl;

* std::cout << "Displacement X: " << disp(0) << std::endl;

* std::cout << "Displacement Z: " << disp(1) << std::endl;

Copilot · 2025-12-04T18:56:08Z

core/specfem/assembly/fields/dim3/simulation_field.hpp

+   * auto elastic_field =
+   * field.get_field<specfem::element::medium_tag::elastic>(); auto displacement
+   * = elastic_field.displacement;


In the code example, the variable name displacement is used but is not defined in the example. The example should show how to properly access displacement from elastic_field.

Suggested change

* auto elastic_field =

* field.get_field<specfem::element::medium_tag::elastic>(); auto displacement

* = elastic_field.displacement;

* auto const& elastic_field =

* field.get_field<specfem::element::medium_tag::elastic>();

* auto const& displacement = elastic_field.displacement;

Copilot · 2025-12-04T18:56:08Z

core/specfem/assembly/fields/data_access/add_on_device.hpp

+ * Public interface for accumulating values into simulation fields on default compute device (GPU when compiled with GPU enabled)
+ * devices. This function provides a unified interface for adding values to


This line appears incomplete with "devices. This function" - there's an awkward break. The sentence should flow directly without the word "devices" appearing standalone.

Suggested change

* Public interface for accumulating values into simulation fields on default compute device (GPU when compiled with GPU enabled)

* devices. This function provides a unified interface for adding values to

* Public interface for accumulating values into simulation fields on the default compute device (GPU when compiled with GPU enabled). This function provides a unified interface for adding values to

Copilot · 2025-12-04T18:56:08Z

core/specfem/assembly/fields/impl/field_impl.hpp

-  using displacement_base_type::get_value;
-  using mass_inverse_base_type::get_value;
-  using velocity_base_type::get_value;
+  // Import get_value methods from all base field types for unified access


The comment "Import get_value methods from all base field types for unified access" could be more precise. Consider: "Bring get_value methods from base classes into scope for unified field access".

Suggested change

// Import get_value methods from all base field types for unified access

// Bring get_value methods from base classes into scope for unified field access

Copilot · 2025-12-04T18:56:09Z

core/specfem/assembly/fields/data_access/store_on_host.hpp

+ * displacement(0) = initial_disp_x;
+ * displacement(1) = initial_disp_z;


In the code example, the variable name displacement is used but the accessor is named disp. The example should be consistent: either use disp(0) = ... or rename the accessor variable to displacement.

Suggested change

* displacement(0) = initial_disp_x;

* displacement(1) = initial_disp_z;

* disp(0) = initial_disp_x;

* disp(1) = initial_disp_z;

Documentation update - Assembly fields

2e10140

Adds documentation for assembly fields

Rohit-Kakodkar requested review from icui and lsawade December 2, 2025 18:04

Rohit-Kakodkar added the ignore-for-release label Dec 2, 2025

Base automatically changed from issue-1387-part-5 to devel December 2, 2025 18:04

icui requested changes Dec 4, 2025

View reviewed changes

core/specfem/assembly/fields/data_access/add_on_device.hpp Outdated Show resolved Hide resolved

core/specfem/assembly/fields/data_access/atomic_add_on_device.hpp Outdated Show resolved Hide resolved

core/specfem/assembly/fields/data_access/load_on_device.hpp Outdated Show resolved Hide resolved

Update core/specfem/assembly/fields/data_access/add_on_device.hpp

025faca

Co-authored-by: Congyue Cui <[email protected]>

Copilot AI review requested due to automatic review settings December 4, 2025 18:51

Rohit-Kakodkar and others added 2 commits December 4, 2025 13:51

Update core/specfem/assembly/fields/data_access/atomic_add_on_device.hpp

b4a51a6

Co-authored-by: Congyue Cui <[email protected]>

Update core/specfem/assembly/fields/data_access/load_on_device.hpp

91a5535

Co-authored-by: Congyue Cui <[email protected]>

Copilot started reviewing on behalf of Rohit-Kakodkar December 4, 2025 18:51 View session

Copilot finished reviewing on behalf of Rohit-Kakodkar December 4, 2025 18:53

Copilot AI reviewed Dec 4, 2025

View reviewed changes

Rohit-Kakodkar requested a review from icui December 8, 2025 14:03

		* auto disp_x = displacement(0);
		* auto disp_z = displacement(1);

		* displacement(0) += delta_disp_x;
		* displacement(1) += delta_disp_z;

		* std::cout << "Displacement X: " << displacement(0) << std::endl;
		* std::cout << "Displacement Z: " << displacement(1) << std::endl;

		* Public interface for accumulating values into simulation fields on default compute device (GPU when compiled with GPU enabled)
		* devices. This function provides a unified interface for adding values to

	// Import get_value methods from all base field types for unified access
	// Bring get_value methods from base classes into scope for unified field access

		* displacement(0) = initial_disp_x;
		* displacement(1) = initial_disp_z;

Documentation update - Assembly fields #1440

Are you sure you want to change the base?

Documentation update - Assembly fields #1440

Uh oh!

Conversation

Rohit-Kakodkar commented Dec 2, 2025

Description

Issue Number

Checklist

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants