Review current examples documentation

[luisaFelixSalles]

Review and comment the existing documentation

General observations

• The examples that have the workflow diagram in the beginning are awesome
• Codes must be commented, we have to make explicit what is written in the code
• The examples should be enumerated. Some examples section assumes that we have looked the examples in a order. That maybe not true for several users, so leave an suggested consultation sequence would be useful
• The examples titles should be highlighted, we would say they are in the same level as the sub titles

Basic examples

Comments:

• Maybe change the name/content of this part
• Always explain acronyms
• Specify in the text which operator is being/ will be used
• Use results files that have more than one variable of the studied object/function/entity
• The plot figures don't have titles neither they show the variable unit
• Maybe an example that explain this: Being able to visualize the correspondence between the results and their representation in a code is not easy for mechanical engineers, for example. It's good to always display/specify the name/reference of a value. For example, with components, we could also define them: we have three values for a displacement, but we don't necessarily know the corresponding direction of each value."
• Why we need a model: explain those small concepts in the examples

Issues found:

• [x] 0. Basic DPF Core usage
  • There is no text that explains what the last code line does
• [x] 1. Operators overview
  • "Operators overview" part: We say that the 'internal name' of a 'raw displacement' is UTOT in the operators' library. In the example text, the concepts of what we're doing here are a bit mixed up
  • "Compute the maximum normalized displacement" part: Change the sentences order:

    #Creation of a "nom field container" operator  
    norm_op = dpf.Operator("norm_fc")
    #connection between the "norm field container" operator's input with the  displacement operator's output
    norm_op.inputs.connect(disp_op.outputs)

    Poorly elaborated sentence	Suggestion
    This allows operators to be “chained” to allow for highly efficient operations.	?
    This example demonstrate how to chain various operators. It connects the input of the operator to the data sources contained within the model object and then the maximum of the norm of the operator.	The goal is to obtain the maximum normalized displacement. First, we connect the data obtained from the ''model'' object to the "U" operator's input. Then we use the "norm_fc" operator and connect it to the previous operator's output . Finally we use the "max/min" operator and connect it with the "norm_fc" operator's output
    Connect to the data sources of the model.	Connection between the model's data and the operator's input
    Finally, get the value of the maximum displacement	Finally, get the value of the maximum of the norm displacement
    because all operators may not be available for a given result.	because some operators may not be available for a given result
    it is much easier to reference available operators by first running:	it is much easier to check/verify the available operators before the first running/ by first running
    "DdataSources" c correct?	?

  • "Scripting operator syntax" part: Nothing is printed in the print command
• [x] 2. Field and field containers overview
  • "Field and field containers overview" part: EN: "A field can be defined on a complete model or on only certain entities of the model based on its scoping. " S: A field can be defined for an entire model or only for certain entities based on its scope
• [x] 3. create our own entities using dpf operators
  • EN: "Piped mesh" ???
  • EN: "Create results over times in a fields container with its time frequency support:" S: … over time…
  • Should this example be here ?
• [x] 5. Bring a fields data locally to improve performance
  • What does it means to manipulate data locally?
  • "Create the workflow" part: Nothing is printed :( i want to be able to see what was done here
  • "Manipulate data locally" part: EN: "This example goes over the fields, keeping the largest invariant value by node if the averaged value of invariants is large enough" S: This example examines the field, retaining the largest invariant value at each node if the average value of the invariants is sufficiently large. I corrected the phrase but the message it wants to send its uncertain (what is large enough)
• [x] 7. Use results helpers to load custom data
  • helpers ? Not explained / we don't see where we're using them (not explicit)
  • "Choose a spatial subset" part: we could show the studied frequency in the plot/ double sense sentence: ''Work on only a named selection (or component)."
• [x] 8. Scope results over custom time domains
  • difference between a step and a sub-step? -" Request specific time steps" part: It would be great to have a example file that have more then one step
  • "Using helpers" part: we don't say what is going to be evaluated
• [x] 9. Scope results over custom space domains
  • "Choose specific nodes" part: we write a code without saying what it is for
  • "Split results depending on spatial properties" part : Poorly elaborated sentence 'The ScopingsContainer entity contains different Scopings and can be connected to any result provider to get results split with the same partition as the input ScopingsContainer '.
• [x] 10. Mathematical Operators
  • Create vectors with different values, so it's easier to understand
  • 'Addition'' part: the number of entities isn't coherent with the explanation of the values quantities needed in the vector/ Why when I print he field1 it says that it has no entities
  • ''Power'' part : we instantiate and call the wrong field / We could explain here too how the calculation is made
  • '' L2 norm''part: We could explain here too how the calculation is made / We could have an example with a 2 entities field
  • '' With scoping"" part: ''With scoping '' doesn't means anything / Not well explained -> we could simply say that the operators will work on the entities with the same scoping ID
• [x] 11. Servers type
  • Non-existent documentation
• [x] 12. Get material properties from the result file
  • More sub-titles are needed
  • In the ''How to get all material properties.'' we have a repeated sentence
  • In the ''How to get all material properties.'' it's said that ''To see which strings are supported, you can print the operator help.'', but nothing is printed when we run the example code

[luisaFelixSalles]

Transient Analysis examples

Comments:

• maybe define a standard method to define the time scoping (ether with the Time_freq_support class either with the results operator input
• maybe define a standard method to input, output and chain the operators

Issues found:

• [x] 0. Transient analysis result example
• I couldn't find anywhere this function description, where we choose one direction. Also the text says: "Plot the minimum and maximum displacements over time for the X component.", is that the X or Z component?

  disp_z = disp.Z()
  disp_z.inputs.time_scoping(timeids)
  min_max_op = ops.min_max.min_max_fc(ops.math.norm_fc(disp_z))

• "Postprocessing stress" part: Don't get this method for the equivalent (von Mises) stress operator. eqv() ?? -" Scoping and stress field coordinates" part:

  
  # Extract a single field from the equivalent stress operator.
  field = eqv.outputs.fields_container()[28]

Print the first node IDs from the field.

print(field.scoping.ids[:10])

The line " Print the first node IDs from the field." doesn't means what it should. Suggestion: " Print the IDs of the first 10 nodes from the field" 
- " Scoping and stress field coordinates" part:  This part doesn't have a good introduction. I got lost. it doesn't describes what is the final goal // The sentence: "As you can see, these node IDs are not in order. Additionally, there may be fewer entries in the field than nodes in the model. For example, stresses are not computed at mid-side nodes." is poorly formulated. Suggestion: s you can see, these node IDs are not in order. Additionally, the results may be given in different places of the mesh. For example stresses are not computed at nodes in the mid-side of an element.

- [x] 1. Choose a time scoping for a transient analysis 
-" Use time extrapolation" part:
```python
offset = 0.0005
time_scoping = [0.05 + offset * i for i in range(0, int((0.08 - 0.05) / offset))]
print(time_scoping)

To complex of a list definition method. It would be great to use a more explicit/visible/understandable method.

[luisaFelixSalles]

Modal analysis examples

Comments:

[!WARNING] ATTENTION EXEMPLE PB !!!! GRAVE

Issues found:

• [x] 0. Use Result Helpers to compare mode shapes for solids and then shells

• Helpers concept? (idk if its me or the users should already know what it is )

• The concepts here are mixed. The text its not well written. If i came to this example because of its title that is not the info i was looking for. The example show us how to get the results in different element shapes, but a mode shape is not that in modal analysis.

• "Choose to split the displacement on solid/shell/beam to only focus on shell elements" this sentence does't make sense and in the end the example show us the displacement results for all the elements shapes: one on ‘solid’, one on ‘shell’, one on ‘beam’ and one on ‘unknown_shape’.

• The plot figure doesn't specify which shape the results are from

• It never explain why we are need to make those functions choices

• Do we have a function that tells us the mode and its frequency? (Because here we print the model and it shows us the f with its index (in the cumulative colum) and i know that when we use workbench it gives us the mode number (in modal analysis this is the basic info we look for)).

• the calss results has this property: split_by_shape

  # Choose to split the displacement on solid/shell/beam to only focus on shell
  # # elements
  # disp = model.results.displacement
  # for mode in modes:
  #     fc = disp.on_time_scoping(mode).split_by_shape.eval()
  #     model.metadata.meshed_region.plot(fc.shell_field())

  Can I use it as a function that accept the element shape as an argument?

• Do we have a function that plot the real mode shape? i couldn't find it->yes, shown in the second example

• [x] 1. Plot and animate mode shapes with DPF

• This example does what the first one proposed and didn't do.

• Each code line is well explained

• "Animate a mode shape To suppress window pop-up, set the off_screen argument to True. ~~~~" ?? this sentence???

• The animation doesn't show us the mode shape (for it we really have to see the deformed mesh )

[luisaFelixSalles]

Harmonic Analysis examples

Comments:

Issues found:

• [x] 0. Multi-harmonic response example

• "Multi-harmonic response example" part: EN: "Read the analysis domain support" -> suggestion: specify that is a time domain and also write what is printed (number of sets)

• Rz component?

  fields = fft.outputs.field_max()
  len(fields)  # one multi-harmonic field response per node

  Why we use the len() function here?

• [x] 1. Expand harmonic modal superposition with DPF

• Maybe explain in a core example of DataDources the concept of "upstream " result need here.

• We don't specify what is plot (we should have a title for each figure)

[luisaFelixSalles]

Advanced and Miscellaneous examples

Comments:

• reorganize this section
• The title means nothing
• Maybe a section "Application examples" with more specific examples would be useful (with the example 10 and 11 for example)

Issues found:

• [x] 0. Multi-stage cyclic symmetry using advanced customization
• why this example is not in the cyclic symmetry section?
• "num_sectors stage " its a quantity?
• Need to explain the used arguments
• Are we able to plot those sectors? So wee can have an idea of what we are going to do
• "Harmonic index 0 means that the results are symmetric sectors by sector taking a node in the base sector of the first stage" ??
• "Check results precisely" part: Divide the text and the prints so we know what is being explained
• [x] 1. Solve harmonic problem (with damping) using matrix inverse
• why this example is not in the "Harmonic analysis " section? // Maybe because we don't use a result file. It could be in the basic section though (just to be with the math_operators example idk)
• "Ma+Dv+Ku=F " this problem has a name-> governing equation of movement
• We should have a diagram or better definition of the problem solved here
• [x] 2. Average elemental stress on a given volume
• Why we make a loop that goes from 1 to 400?
• streams? i don't get it
• "minimum list of elements" doesn't make sense
• it never explains what the operator/ class does
• "Find the minimum list of elements by node to get the volume check" part: too long and too complex for the amount of code commented
• This example should be part of the "Averaging section" as an advanced example
• The fact that we have an algorithm that does all of this should be announced at the beginning
• What is plotted , The volume or the stress?
• Bad figure legend
• [x] 3. Exchange data between servers
• This example should be in the "Distributed post-processing" section
• [x] 4. Extrapolation method for stress result of a 3D element
• Should be in the "Averaging" section
• "This example uses the gauss_to_node_fc operator" and proceeds to not using it
• "The MAPLD command ERESX,NO is used to copy directly the Gaussian (integration) points results to the nodes, instead of the results at nodes or elements (which are interpolation of results at a few gauss points). The following plot shows the nodal values, which are the averaged values of stresses at each node. The value shown at the node is the average of the stresses from the Gaussian points of each element that it belongs to." confusing paragraph, mainly the last sentence
• "Compare stress results" part: needs a conclusion
• "Compute absolute and relative errors" part: comment the code
• We could have the part "Compare results" as an separate example
• [x] 5. Extrapolation method for strain result of a 2D element
• Should be in the "Averaging" section
• Same comments of the example 4
• [x] 6. Stress gradient normal to a defined node
• "Define the node ID normal to plot the a stress gradient" -> how it was chosen?
• Well explained example
• [x] 7. Load plugin
• "Create a base service for loading a plugin:" could be better explained (what the code does)
• [x] 10. Pressure vessel analysis according to an ASME standard
• "as specified in Equation 5.7 a ..." which equation??
• How the poisson ratio is corrected?
• Coded needs more comments
• We don't explain how the operators works ( like the component_wise_divide one)
• I don't get what is plotted. The strain ration in the vessel? What is it in the figure (a vessel? a car? a banana? a line ? )
• [x] 11. Calculate the number of cycles to fatigue failure
• sentences/ paragraphs format is awkward
• SN curve data is not explained
• [x] 12. Read results from distributed files
• Should be in the "Distributed post-processing" section
• [x] 13. Manage the DPF licensing logic using the server context
• "Operators with the Entry context" part: link the prints to their code lines
• [x] 14. Use incremental evaluation helper
• Should be in a section with the "Use results helpers to load custom data" example (that is currently in the Basic examples section)
• "This example shows you how to use the incremental evaluation helper." ok but what it does? what is its function
• "In this example we want to compute the min/max for all the time sets" Min/max of what?
• "If you don't need to reuse TimeFreqSupport you could... " ?? EN
• ok but what is the "incremental evaluation helper"? where is it ?

[luisaFelixSalles]

File manipulation and input-output

Comments:

• It doesn't presents all types of files

Issues found:

• [x] 0. HDF5 export and compare precision
• Need to explain better what defines the difference in the code when using single and double precision
• "Download the resulting .h5 files if necessary" ???
• "Compare simple precision versus double precision." part: size of what? unit?
• [x] 1. Get reduced matrices and make export
• "Get reduced matrices and make export" -> why?
• [x] 2. HDF5 export and import operations
• The code needs to be better explained/ commented
• [x] 4. Working with a result file
• Not a great title for this example
• "Subtract the two fields and plot an error map:" is that really an error map?
• We really need a section that has error/ results comparison examples

[luisaFelixSalles]

Plotting examples

Comments:

• The use of operators here is weird as it shows a format only used in this section without keyword arguments

Issues found:

• [x] 0.Review of available plotting commands
• Divide the code and let each individual image after the code part// or even enumerate the images and the comments line in the code
• We have several figures with the same title
• What is the difference between the bare mesh and the meshed region? Maybe use a different analysis result file here to make explicit this difference
• Is really hard to keep going up and down to find which code part represents which figure
• What is the difference between "Plot a field on its supporting mesh" and " A fields_container or a specific field can be given to plot on the mesh."
• Why when we run the code we don't have all the same figures as we have in the example documentation?
• This example needs more explicit figures titles and texts
• "A fields_container can be given as input, with results on each part of our split mesh." i don't get it. Maybe because of the results, we don't see the mesh divisions.
• [x] 1.Compare results using the plotter
• Why do we need to create a deep copy?
• I don't get what us done here, the code is not sufficiently commented.
• What are we "appending"? in:

  overall_field = dpf.fields_factory.create_3d_vector_field(1, dpf.locations.overall)
  overall_field.append([0.2, 0.0, 0.0], 1)

• What are we doing with the coordinates ?
• Isn't there a easier way of displaying 2 results in the same figure using DPF plotter?
• [x] 2.Load case combination for principal stress
• great examples
• [x] 3.Add nodal labels on plots
• cpos?? (explanation in the end but why )
• [x] 4.Plot results on a specific path
• "Create a coordinates field to map on." part: explain what the code is doing, like the loop lines
• "Compute the mapped data using the mapping operator." it doesn't explain what this operator does
• [x] 5.Warp the mesh by a field for plotting
• It would be useful to have "for plotting on the deformed geometry." in this example title
• Divide the code and let each individual image after the code part// or even enumerate the images and the comments line in the code // Is really hard to keep going up and down to find which code part represents which figure
• [x] 6.Review of available animation commands
• We could have more text instead of just code comments
• We don't have documentation over animation, just this example
• [x] 7. Plot on geometry elements
• We have a good explanation of "cpo" (camera position) it should be in the others too
• ansys.dpf.core.geometry?? do we have any doc?
• We don't see the diagonal in the website

• The line created in the example code is not the diagonal of the geometry

• How do we chose the coordinates?

[luisaFelixSalles]

Examples for post-processing on distributed processes

Comments:

• The examples tat have the workflow diagram in the beginning are awesome
• This section assumes that we have looked the examples in a order, but that maybe not true for several users. Some really useful explanations are not repeated in all the examples. So it would be great to repeat the explanations in all the examples or to make explicit that the examples should be read in a order

Issues found:

• [x] 0. Post-processing of displacement on distributed processes
• It really explains what the is done in the code !! nice :)
• The merge the results is juts putting the 2 results in the same field?
• [x] 1.Create a custom workflow on distributed processes
• what is "mul" ? We just discover that almost in the end of the example
• [x] 2.Distributed mode superposition (MSUP)
• "Connect the operator chains together and get the output" part: Why those ids? // What is plotted? we don't have a title
• [x] 3.Distributed MSUP distributed modal response
• Idk if it is the results file but the mesh looks like it got an error

like it has this triangle in the middle (empty) and a triangle breaking the symmetry in the upper left corner

• [x] 6. Distributed stress averaging
• This example doesn't have a documentation file. We just have the code in the PyDPF- Core folder I downloaded

[luisaFelixSalles]

Examples of creating custom operator plugins

Comments:

• These examples have a great introduction, but when we go to the code there is no explanation on what which thing represents

Issues found:

• [x] 0.Create a basic operator plugin
• why here is really hard and long to download the example file?
• As the code is not commented is really hard to get what is first printed (nor what is coded)/ Is there a example on how to create a operator?
• " Load the plugin part": is great that its said what each argument represents, but it would be greater to separate the explanation in the lines of the code

  # Python plugins are not supported in process.
  dpf.start_local_server(config=dpf.AvailableServerConfigs.GrpcServer)

  The first line here ?

• [x] 1. Create a plug-in package with multiple operators
• Routines for DPF?
• Comment/explain the code
• There are several prints together, is hard to know which part of the code represents which print
• I don't get the difference with the first example in this part
• [x] 2. Create a plug-in package that has third-party dependencies
• When, why would i be in this case?
• A lot of unexplained code
• "Use the custom operator" part: we would love to see some results printed

[luisaFelixSalles]

Averaging examples

Comments:

Issues found:

• [x] 0. Averaging order
• The fact that this example draws the workflow at the beginning is incredible
• "This example compares two different workflows that accomplish the same task to show how the order of the operators can change the end result." If they give different results they do not accomplish the same task.
• "Plot the results": we do not plot here, we print.
• Conclusion????? Which order should I use?????????????????
• [x] 1.Average across bodies
• Good explanation of the goal of the example at the beginning
• "To visualize the model and see how the bodies are connected, extract their individual meshes using the split_mesh operator with the mat (or “material”) property." why do we make this choice?
• "pass a scopings container the stress operator that contains the elements of each body in scopings, separated by the mat label" ???
• Explain why we use the weights on the pin 1000 to 1 (i'm not sure that i understood it right )
• Conclusion ????

[luisaFelixSalles]

Mesh operations examples

Comments:

Issues found:

• [x] 0. Create and display a mesh with polygon and polyhedron elements
• Comment a little bit more the code
• [x] 5. Extract the skin from a mesh
• The title is confusing. We would say we want to erase the mes skin, not keep just the mesh skin.
• Comment the code
• "Manipulate data locally" part: what is large enough?
• [x] 13. Convert nodal coordinates field to local coordinate system

  cs = model.operator(r"mapdl::rst::CS")
  cs.inputs.cs_id.connect(12)
  cs_rot_mat = cs.outputs.field.get_data().data.T[0:9]

  The first line??? //"The first 9 values in the cs output is the rotation matrix." Always the firs 9 values?

• This example is well written, it explains what is being done

[luisaFelixSalles]

Cyclic symmetry examples

Comments:

Issues found:

• [x] 0. Expand mesh and results for modal cyclic symmetry
• "Expand displacement results" part: Fist time step? or first mode/ first frequency?
• Showing the base geometry would be great
• "Expand stresses at a given time step" part: we don't have the plot
• "Expand stresses and average to elemental location" : this title can be misunderstood
• [x] 1. Get base and duplicate sectors (real and imaginary) results for modal cyclic symmetry
• "Get base and duplicate sectors displacement results" part: this explanation should be in the first example
• "The print also displays that there is no duplicate sectors for the first 6 modes. Indeed, modes with harmonic index 0 have 0.0 displacement, stresses… on duplicate sectors." : where? why the explanation comes first?
• ansys.dpf.result.cyclic_expanded_displacement this exists ?
• [x] 2. Multi-stage cyclic symmetry example
• "Expand displacement results" part: "# expand the displacements and get a total deformation" deformation?
• This examples is the exact copy of the first one, it doesn't really study the manipulation o the different sub-steps.

[luisaFelixSalles]

Fluids examples

Comments:

Issues found:

• [x] 0. Explore Fluids models
• This is actually a great example on how to explore a model

formating? and thus sentence is too large

• "Each body is comprised of a set of cell zones. You can investigate the hierarchical relationship between bodies and cell zones through the “body_cell_topology” PropertyField, which provides a relationship between the body IDs and the cell zone IDs. In this case, each body is only comprised of one cell zone." sentence is too large. the next sentence is not coherent with the first one.
• "Each result holds more detailed information while explored individually. En..." the explanation should come after the printed code
• Exploring an Ansys CFX model" part is the same example in the "CFX examples" section but it is better written
• [x] 1. Explore Fluids mesh
• We have the same title for all the doc parts
• actually a great example
• [x] 2. Explore Fluids results
• Why we need the streams? not explained
• "Elemental results do not bring their MeshSupport by default, and thus the mesh input can be employed to connect the MeshedRegion and display the result".-> "..., and thus..." is a verbal use of this term, we don't write the "and". In addition I think this is not correctly employed, i don't think the goal here was to show a "consequence" in this sentence (nevertheless makes more sense here ) // Again the explanation could come after the print// We print a lot of things and show them together, it would be great to separate them // What is "cpos", where those values came from?????
• The second part here also has a long text after a code that is difficult to understand because is not commented. Even the text is not useful to understand the code. I don't get what we are doing here, we plot 2 times the same thing?
• The rest of the example has the same errors. In addition it gets more complex, if i didn't get the begging i'm not going to get the rest of it
• [x] 3. Compute iso-surfaces on fluid model
• "Specify the file path." part: Why we need the streams? not explained -"Whole mesh scoping." part: " We evaluate the mesh with the mesh_provider operator to scope the mesh_cut operator with the whole mesh." -> why we speak of mesh_cut, we don't even use that here
• "Extract the physics variable" part: what?
• "Evaluate iso-surfaces" part: why and how do we chose those surfaces?
• The important note should be at the beggning!!!!!

[luisaFelixSalles]

Streamlines examples

Comments:

• Make more comments on the code

Issues found:

• [x] 0. Compute and plot 3D streamlines
• "Compute and plot the streamlines adjusting the request" part: text is too long, it should be divided in the code// EN: " If permissive is set to False, the “add_streamlines” method throws." ???
• What is the first plot?
• Explain what the streamline source is
• "Compute and plot streamlines from several sources" part: we just have a bunch of code, it could be more commented/ explained
• [x] 1. Compute and plot 2D streamlines
• we just have a bunch of code, we could comment/ explain what we are doing
• The only part hat have a little explanation is: "Plot single streamline"

[luisaFelixSalles]

LS-Dyna Examples

Comments:

• Explain why and when we should use which type of results file
• Explain better how the code woks and use different terms.

Issues found:

• [x] 0. Results extraction and analysis from LS-Dyna sources

• "d3plot file results extraction" part: The text says: "The model has solid (3D) elements and beam (1D) elements. Some of the results only apply to one type of elements (such as the stress tensor for solids, or the axial force for beams, for example)." It would be great to have a code that print this correlation (which results is given for which type of element )

• it doesn't explain why we are doing those things: "Let’s extract beam axial force for the last time step and plot it, deforming the mesh according to the displacement field at the same time step."

• The figure show us values but doesn't indicates what they are, a force?

• I don't get the conclusion of this part: "The axial force has only been computed for the beam elements..."

• "binout file results extraction" part: spelling error : "Create the model and dprint its contents. " -> dprint? -" Results from the matsum branch of the binout file " ??? don't understand this sentence.

[luisaFelixSalles]

CFX examples

Comments:

• Too simple, it looks like the first example of the basic examples section

Issues found:

• [x] 0. Read CFX .res files
• "Exploring an Ansys CFX .res file" part: it doesn't actually shows how to load an Ansys CFX .res file
• What is the difference between:

  result_info = model.metadata.result_info
  print(result_info.available_results)
  # and
  print(model.results)

  i think the first is just a longer method and it prints all the info in just one line (confusing)