Variable hydro documentation #1343

akeeste · 2024-10-16T20:53:00Z

This PR adds documentation on the variable hydro advanced feature:

user advanced feature section
developer advanced feature section
explain flags (hydroForceIndexInitial, option, etc)
compatibility between variable hydro and other features (GBM, SS, FIR filter, user defined excitation force)

akeeste · 2024-10-23T20:29:30Z

This is now ready for an initial review. As I was the one who created the feature, I don't have a good sense of what users will need detailed documentation on. I could use a review and suggestions about additional content to cover.

…eHydroDocs

kmruehl

@akeeste I reviewed this content, and I have several recommendations. I'll put my commends in the review, and then we can discuss how to rework the documentation. I'm happy to help rewrite the text.

kmruehl · 2024-10-31T22:28:22Z

docs/_include/variable_hydro.rst

+a specific scenario, state, signal, or discretization required. It is the 
+user's responsibility to implement a specific variable hydrodynamics case
+using best practices and validate the results with higher fidelity data.
+


This section is that first one that users will read. I recommend simplifying it to clearly describe what/how variable hydro works, and then provide an example. Here's my initial attempt:

Variable hydrodynamics allows WEC-Sim bodies to simulate bodies with hydrodynamic data from multiple BEM runs for a single body. Hydrodynamic data from each BEM run is parsed into H5 files, which are then initialized in the instance of the body class, for example body(1) = bodyClass({'H5FILE_1.h5','H5FILE_2.h5',...);. This feature allows users to simulate bodies with different initial conditions, for example body that is floating or submerged. Users then specify the condition to switch when each H5 is used. The condition must be based on a WEC-Sim state...

@akeeste I used ChatGPT to refine the overview and here's the suggestion:

Overview

Variable Hydrodynamics enables WEC-Sim bodies to utilize hydrodynamic data from multiple BEM runs within a single body instance. Each BEM run's data is stored in H5 files, which are initialized in the body class, for example:

body(1) = bodyClass({'H5FILE_1.h5', 'H5FILE_2.h5', ...});

This feature allows users to simulate different initial conditions, such as floating or submerged states. Users specify the conditions that trigger the use of each H5 file, based on a WEC-Sim state.

I agree this text could be more concise, I'll revise this text.

The ChatGPT response is certainly concise, bit its inaccurate when for some of the details (H5 files aren't being initialized, the feature is not about initial conditions)

kmruehl · 2024-10-31T22:30:53Z

docs/_include/variable_hydro.rst

+multiple hydrodynamic datasets at various pitch angles (-50:10:50). It is most convenient
+to treat these angles in numerical order in BEM simulations, indexing logic, and other 
+data processing. In this case the initial position is at a pitch angle of 0 so ``body.variableHydro.hydroForceIndexInitial=6;``.
+


This level of detail seems more appropriate for the developer documentation. I recommend simplifying the user docs to only what the user needs to know to implement the feature, which is that they need to specify which index to start with. I don't even know how critical it is for a user to understand the bus signals.

Here is the ChatGPT recommendation for Implementation

Implementation

To implement Variable Hydrodynamics, follow these steps:

Initialize the Body: Create a body instance with a cell array of H5 files containing the hydrodynamic data. For example:

body(1) = bodyClass({'H5FILE_1.h5', 'H5FILE_2.h5', 'H5FILE_3.h5', ...});

Enable Variable Hydrodynamics: Set the variableHydro.option flag to enable the feature:

body(1).variableHydro.option = 1;

Set Initial Hydrodynamic Coefficient Index: Use the hydroForceIndexInitial flag to define the default index for hydrodynamic coefficients, typically representing the body’s starting condition:

body(1).variableHydro.hydroForceIndexInitial = <initial_index>;

Simulink Integration: Load the hydrodynamic force data into Simulink using a custom bus. Create a GoTo block named body1_hydroForceIndex (or similar) to allow the body block to read the index signal for selecting the appropriate hydrodynamic coefficients.

User-Defined Logic: Implement your own logic in Simulink to determine when to switch between H5 files based on the specified conditions.

Note: Variable hydrodynamics can be applied to individual bodies in a simulation, and it is not necessary for all bodies.

I like the suggested numbering of steps for a user's implementation. I combined this with the detailed paragraphs to walk a user through set-up.

docs/_include/variable_hydro.rst

kmruehl · 2024-10-31T22:35:31Z

docs/_include/variable_hydro.rst

+* Validate using high fidelity data
+* The hydroData directory may become very large
+* All BEM data is contained within the ``body`` variable. Pre-processing remains very fast, so it's not recommended to save ``body`` to an output file or the file size may increase drastically.
+* Conditions that require a varying mass, center of gravity, or center of buoyancy are not yet implemented.


Similar comment, I this this is better suited as a note that this feature should be used with extreme caution. I also recommend moving a lot of these recommendations to the README in the variable hydro application case.

I can change this to a note or paragraph, but I don't think the notes will be read if moved to the Application readme. Those documents tend to contain very basic information about a specific case, whereas these tips will be applicable to any simulation with variable hydrodynamics

kmruehl

I recommend using ChatGPT to improve our documentation. I fed it your text, my text, and then asked it to make docs clearer and more concise. I think it did a pretty good job.

kmruehl · 2024-10-31T22:44:12Z

docs/_include/variable_hydro.rst

+a specific scenario, state, signal, or discretization required. It is the 
+user's responsibility to implement a specific variable hydrodynamics case
+using best practices and validate the results with higher fidelity data.
+


@akeeste I used ChatGPT to refine the overview and here's the suggestion:

Overview

Variable Hydrodynamics enables WEC-Sim bodies to utilize hydrodynamic data from multiple BEM runs within a single body instance. Each BEM run's data is stored in H5 files, which are initialized in the body class, for example:

body(1) = bodyClass({'H5FILE_1.h5', 'H5FILE_2.h5', ...});

This feature allows users to simulate different initial conditions, such as floating or submerged states. Users specify the conditions that trigger the use of each H5 file, based on a WEC-Sim state.

kmruehl · 2024-10-31T22:48:51Z

docs/_include/variable_hydro.rst

+multiple hydrodynamic datasets at various pitch angles (-50:10:50). It is most convenient
+to treat these angles in numerical order in BEM simulations, indexing logic, and other 
+data processing. In this case the initial position is at a pitch angle of 0 so ``body.variableHydro.hydroForceIndexInitial=6;``.
+


Here is the ChatGPT recommendation for Implementation

Implementation

To implement Variable Hydrodynamics, follow these steps:

Initialize the Body: Create a body instance with a cell array of H5 files containing the hydrodynamic data. For example:

body(1) = bodyClass({'H5FILE_1.h5', 'H5FILE_2.h5', 'H5FILE_3.h5', ...});

Enable Variable Hydrodynamics: Set the variableHydro.option flag to enable the feature:

body(1).variableHydro.option = 1;

Set Initial Hydrodynamic Coefficient Index: Use the hydroForceIndexInitial flag to define the default index for hydrodynamic coefficients, typically representing the body’s starting condition:

body(1).variableHydro.hydroForceIndexInitial = <initial_index>;

Simulink Integration: Load the hydrodynamic force data into Simulink using a custom bus. Create a GoTo block named body1_hydroForceIndex (or similar) to allow the body block to read the index signal for selecting the appropriate hydrodynamic coefficients.

User-Defined Logic: Implement your own logic in Simulink to determine when to switch between H5 files based on the specified conditions.

Note: Variable hydrodynamics can be applied to individual bodies in a simulation, and it is not necessary for all bodies.

…eHydroDocs

akeeste · 2024-11-06T20:32:33Z

@kmruehl I made some revisions to the documentation based on your suggest. See above comments. Given the challenges of using this feature, I think it is worth leaving more detail and explanation for users than less. Let me know if you think there is any topic missing.

kmruehl · 2024-11-27T14:51:32Z

@akeeste thanks, I'll review it again. Also, do you know why the documentation build isn't passing?

akeeste · 2024-12-02T15:37:19Z

@akeeste thanks, I'll review it again. Also, do you know why the documentation build isn't passing?

Some issue with one of the images I pushed, but otherwise the test's error message is unclear. My build works locally. I'll test again with the most up to date conda environment

akeeste · 2024-12-02T16:07:49Z

@kmruehl The issue is fixed. Linux filenames are case sensitive but windows filenames are not so the build passed locally and failed on Actions.

akeeste added 3 commits October 16, 2024 14:45

update refernces to hydroforce in documentation

979f23b

initial setup

f980b2d

variable hydro docs v1

25293f5

akeeste added the Documentation related to docs label Oct 16, 2024

akeeste added 2 commits October 23, 2024 14:09

update variable hydro advanced feature

8455ec6

add variable hydro to documentations application list

4cc8623

akeeste linked an issue Oct 23, 2024 that may be closed by this pull request

[Developer Issue] Add Variable Hydrodynamics Documentation #1310

Open

1 task

variable hydro developer docs

ccc06f8

akeeste marked this pull request as ready for review October 23, 2024 20:29

kmruehl self-assigned this Oct 23, 2024

kmruehl self-requested a review October 23, 2024 20:31

akeeste added 4 commits October 30, 2024 10:39

explain variable hydro flags used in wecsiminputfile

1c14829

Merge branch 'dev' of https://github.com/WEC-Sim/WEC-Sim into variabl…

177890b

…eHydroDocs

hopefully fix bullet issue

9f9437e

add compatibility section

30fe939

kmruehl requested changes Oct 31, 2024

View reviewed changes

kmruehl reviewed Oct 31, 2024

View reviewed changes

akeeste added 5 commits November 6, 2024 11:37

Merge branch 'dev' of https://github.com/WEC-Sim/WEC-Sim into variabl…

49fe2d7

…eHydroDocs

make compatibility a note

cceb135

revise user implementation section

ef3597d

revise additional considerations section

0093cdd

revise intro a bit

9d56f42

akeeste added 3 commits December 2, 2024 09:46

update image path

97210e5

fix file type capitalization for linux docs build

6880634

typo fix

111def7

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Variable hydro documentation #1343

Variable hydro documentation #1343

akeeste commented Oct 16, 2024 •

edited

Loading

akeeste commented Oct 23, 2024

kmruehl left a comment

kmruehl Oct 31, 2024

kmruehl Oct 31, 2024

akeeste Nov 6, 2024

kmruehl Oct 31, 2024

kmruehl Oct 31, 2024

akeeste Nov 6, 2024

kmruehl Oct 31, 2024

akeeste Nov 6, 2024

kmruehl left a comment •

edited

Loading

kmruehl Oct 31, 2024

kmruehl Oct 31, 2024

akeeste commented Nov 6, 2024

kmruehl commented Nov 27, 2024

akeeste commented Dec 2, 2024 •

edited

Loading

akeeste commented Dec 2, 2024

Variable hydro documentation #1343

Are you sure you want to change the base?

Variable hydro documentation #1343

Conversation

akeeste commented Oct 16, 2024 • edited Loading

akeeste commented Oct 23, 2024

kmruehl left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Overview

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Implementation

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kmruehl left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Overview

Choose a reason for hiding this comment

Implementation

akeeste commented Nov 6, 2024

kmruehl commented Nov 27, 2024

akeeste commented Dec 2, 2024 • edited Loading

akeeste commented Dec 2, 2024

akeeste commented Oct 16, 2024 •

edited

Loading

kmruehl left a comment •

edited

Loading

akeeste commented Dec 2, 2024 •

edited

Loading