From f383b936046aedecaf41800c25546d494012b835 Mon Sep 17 00:00:00 2001 From: juddmehr Date: Mon, 15 Apr 2024 11:15:22 -0600 Subject: [PATCH] start some basic docs --- docs/.gitignore | 2 + docs/Project.toml | 7 + docs/assets/plots_default.jl | 297 ++++++++++++++++++++++++++++ docs/make.jl | 22 +++ docs/src/api.md | 7 + docs/src/examples.md | 11 ++ docs/src/index.md | 22 +++ docs/src/theory.md | 1 + docs/src/tutorial.md | 364 +++++++++++++++++++++++++++++++++++ 9 files changed, 733 insertions(+) create mode 100644 docs/.gitignore create mode 100644 docs/Project.toml create mode 100644 docs/assets/plots_default.jl create mode 100644 docs/make.jl create mode 100644 docs/src/api.md create mode 100644 docs/src/examples.md create mode 100644 docs/src/index.md create mode 100644 docs/src/theory.md create mode 100644 docs/src/tutorial.md diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 00000000..a303fff2 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,2 @@ +build/ +site/ diff --git a/docs/Project.toml b/docs/Project.toml new file mode 100644 index 00000000..47054d29 --- /dev/null +++ b/docs/Project.toml @@ -0,0 +1,7 @@ +[deps] +Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" +DuctAPE = "ad8e49fd-fab7-444e-af4a-0daba3b8bf11" +GR = "28b8d3ca-fb5f-59d9-8090-bfdbd6d07a71" +LaTeXStrings = "b964fa9f-0449-5b57-a5c2-d3ea65f4040f" +Measures = "442fdcdd-2543-5da2-b0f3-8c86c306513e" +Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80" diff --git a/docs/assets/plots_default.jl b/docs/assets/plots_default.jl new file mode 100644 index 00000000..729e5a4f --- /dev/null +++ b/docs/assets/plots_default.jl @@ -0,0 +1,297 @@ +using Plots +gr() +using LaTeXStrings +using Measures + +default() +default(; + # #:Plot + # background_color=RGBA(1, 1, 1, 0), + # background_color = nothing, + # background_color_outside = nothing, + # display_type, + # dpi, + # extra_kwargs, + # extra_plot_kwargs, + fontfamily="Computer Modern", + # foreground_color, + # html_output_format, + # inset_subplots, + # layout, + # link, + # overwrite_figure, + # plot_title, + # plot_title_location, + # plot_titlefontcolor, + # plot_titlefontfamily, + # plot_titlefonthalign, + # plot_titlefontrotation, + # plot_titlefontsize, + # plot_titlefontvalign, + # pos, + # show, + size=(400, 300) .* 5.0 ./ 4.0, #it appears that 100 ≈ 1inch in LaTeX + # size=(600, 450), #it appears that 100 ≈ 1inch in LaTeX + # size=(800, 600), #it appears that 100 ≈ 1inch in LaTeX + # tex_output_standalone, + # thickness_scaling, + # warn_on_unsupported, + # window_title, + + ####################### + # :Series + ####################### + # arrow, + # bar_edges, + # bar_position, + # bar_width, + # bins, + # colorbar_entry, + # connections, + # contour_labels, + # contours, + # extra_kwargs, + # fill_z, + fillalpha=0.125, + fillcolor=RGB(128 / 255, 128 / 255, 128 / 255), + # fillrange, + # group, + # hover, + # label, + # levels, + # line_z, + # linealpha, + # linecolor, + # linestyle, + linewidth=1.0, + # marker_z, + # markeralpha, + # markercolor, + # markershape, + markersize=3, + markerstrokealpha=0, + # markerstrokecolor, + # markerstrokestyle, + # markerstrokewidth, + # normalize, + # orientation, + # primary, + # quiver, + # ribbon, + # series_annotations, + # seriesalpha, + # seriescolor, + # seriestype, + # show_empty_bins, + # smooth, + # stride, + # subplot, + # weights, + # x, + # xerror, + # y, + # yerror, + # z, + # zerror + + ####################### + # :Subplot + ####################### + # annotationcolor, + annotationfontfamily="Computer Modern", + annotationfontsize=10, + # annotationhalign, + # annotationrotation, + # annotations, + # annotationvalign, + # aspect_ratio, + background_color_inside=nothing, + background_color_legend=nothing, + background_color_subplot=nothing, + # bottom_margin, + # camera, + # clims, + color_palette=[ + #polynesian blue + RGB(0 / 255, 75 / 255, 150 / 255), + #004B96 + #argentinian blue + RGB(100 / 255, 175 / 255, 250 / 255), + #64AFFA + #imperial red + RGB(250 / 255, 75 / 255, 75 / 255), + #FA4B4B + #melon + RGB(250 / 255, 175 / 255, 150 / 255), + #FAAF96 + #lime green + RGB(75 / 255, 200 / 255, 75 / 255), + #4BC84B + #light green + RGB(150 / 255, 250 / 255, 150 / 255), + #96FA96 + ], + #color_palette=[ + # RGB(0.0, 46.0 / 255.0, 93.0 / 255.0), #BYU Blue + # RGB(155.0 / 255.0, 0.0, 0.0), #"BYU" Red + # RGB(128.0 / 255.0, 128.0 / 255.0, 128.0 / 255.0), #Middle Gray + # RGB(162.0 / 255.0, 227.0 / 255.0, 162.0 / 255.0), #Light Green + # RGB(243.0 / 255.0, 209.0 / 255.0, 243.0 / 255.0), #Pink + # RGB(205.0 / 255.0, 179.0 / 255.0, 0.0), #Yellow + # RGB(161.0 / 255.0, 161.0 / 255.0, 226.0 / 255.0), #Purple + #], + # colorbar, + # colorbar_continuous_values, + # colorbar_discrete_values, + # colorbar_fontfamily, + # colorbar_formatter, + # colorbar_scale, + # colorbar_tickfontcolor, + # colorbar_tickfontfamily, + # colorbar_tickfonthalign, + # colorbar_tickfontrotation, + # colorbar_tickfontsize, + # colorbar_tickfontvalign, + # colorbar_ticks, + # colorbar_title, + # colorbar_title_location, + # colorbar_titlefontcolor, + # colorbar_titlefontfamily, + # colorbar_titlefonthalign, + # colorbar_titlefontrotation, + # colorbar_titlefontsize, + # colorbar_titlefontvalign, + # extra_kwargs, + # fontfamily_subplot, + foreground_color_legend=nothing, + # foreground_color_subplot, + # foreground_color_title, + # framestyle = :zerolines, + # left_margin, + # legend=false, # include legend true/false + # legendfontcolor, + # legendfontfamily, + # legendfonthalign, + # legendfontrotation, + # legendfontsize, + # legendfontvalign, + # legendtitle, + # legendtitlefontcolor, + # legendtitlefontfamily, + # legendtitlefonthalign, + # legendtitlefontrotation, + # legendtitlefontsize, + # legendtitlefontvalign, + margin=5mm, + # projection, + # right_margin, + # subplot_index, + # title, + # titlefontcolor, + # titlefontfamily, + # titlefonthalign, + # titlefontrotation, + # titlefontsize, + # titlefontvalign, + # titlelocation, + # top_margin + + ##################### + # :Axis + ##################### + # discrete_values, + # draw_arrow, + # flip, + # foreground_color_axis, + # foreground_color_border, + # foreground_color_grid, + # foreground_color_guide, + # foreground_color_minor_grid, + # foreground_color_text, + # formatter, + grid=false, # background grid true/false + # gridalpha, + # gridlinewidth=0.5, + # gridstyle, + # guide, + # guide_position, + # guidefontcolor, + # guidefontfamily, + # guidefonthalign, + # guidefontrotation, + # guidefontsize, + # guidefontvalign, + # ylims=(0, 3), + # xlims=(0, 2), + # link, + # minorgrid, + # minorgridalpha, + # minorgridlinewidth, + # minorgridstyle, + # minorticks, + # mirror, + # rotation, + # scale, + # showaxis = false, #turns off spines and tick labels, but not ticks + # tick_direction, + # tickfontcolor, + # tickfontfamily, + # tickfonthalign, + # tickfontrotation, + # tickfontsize, + # tickfontvalign, + # ticks=false, #turns off tick marks + # widen, +) + +myblue = [ + #oxford blue + RGB(0 / 255, 25 / 255, 50 / 255), + #01932 + #polynesian blue + RGB(0 / 255, 75 / 255, 150 / 255), + #004B96 + #argentinian blue + RGB(100 / 255, 175 / 255, 250 / 255), + #64AFFA +] +myred = [ + #dark purple (very dark red) + RGB(50 / 255, 0 / 255, 25 / 255), + #320019 + #imperial red + RGB(250 / 255, 75 / 255, 75 / 255), + #FA4B4B + #melon + RGB(250 / 255, 175 / 255, 150 / 255), + #FAAF96 +] +mygreen = [ + #dark green + RGB(0 / 255, 50 / 255, 25 / 255), + #003219 + #lime green + RGB(75 / 255, 200 / 255, 75 / 255), + #4BC84B + #light green + RGB(150 / 255, 250 / 255, 150 / 255), + #96FA96 +] +mygray = [ + #battleship gray + RGB(150 / 255, 150 / 255, 150 / 255), + #969696 + #davy's gray + RGB(75 / 255, 75 / 255, 75 / 255), + #4B4B4B +] + +#mycolors = [ +# RGB(0, 46 / 255, 93 / 255), #BYU Blue +# RGB(155 / 255, 0, 0), #"BYU" Red +# RGB(128 / 255, 128 / 255, 128 / 255), #Middle Gray +# RGB(162 / 255, 277 / 255, 162 / 255), #Light Green +# RGB(243 / 255, 2090 / 255, 243 / 255), #Pink +# RGB(205 / 255, 179 / 255, 0.0), #Yellow +# RGB(161 / 255, 161 / 255, 226 / 255), #Purple +#] diff --git a/docs/make.jl b/docs/make.jl new file mode 100644 index 00000000..e86bb7f8 --- /dev/null +++ b/docs/make.jl @@ -0,0 +1,22 @@ +using Documenter +using DuctAPE + +makedocs(; + modules=[DuctAPE], + format=Documenter.HTML(; + repolink="https://github.com/byuflowlab/DuctAPE.jl/blob/{commit}{path}#L{line}", + edit_link="main", + ), + pages=[ + "Home" => "index.md", + "Getting Started" => "tutorial.md", + "Examples" => "examples.md", + "API Reference" => "api.md", + "Theory" => "theory.md", + ], + sitename="DuctAPE.jl", + authors="Judd Mehr ", + checkdocs=:exports, +) + +deploydocs(; repo="https://github.com/byuflowlab/DuctAPE.jl.git", devbranch="main") diff --git a/docs/src/api.md b/docs/src/api.md new file mode 100644 index 00000000..5600eb6d --- /dev/null +++ b/docs/src/api.md @@ -0,0 +1,7 @@ +# API Reference + +## Public API + +## Private API + +## Index diff --git a/docs/src/examples.md b/docs/src/examples.md new file mode 100644 index 00000000..779d35e0 --- /dev/null +++ b/docs/src/examples.md @@ -0,0 +1,11 @@ +# Examples + +## Advanced Option Selection + +## Available Outputs + +## Returning the Pre-process objects + +## Multi-Point Analyses + +## Circumventing the Automated Geometry Re-paneling diff --git a/docs/src/index.md b/docs/src/index.md new file mode 100644 index 00000000..59a99d83 --- /dev/null +++ b/docs/src/index.md @@ -0,0 +1,22 @@ +# DuctAPE.jl [[Duct](#)ed [A](#)xisymmetric [P](#)ropulsor [E](#)valuation] + +Authors: Judd Mehr, + +DuctAPE is a code for the aerodynamic evaluation of axisymmetric ducted propulsors designed for incompressible (low mach) applications. +It is strongly influenced by the underlying [theory](https://web.mit.edu/drela/Public/web/dfdc/DFDCtheory12-31.pdf) of Ducted Fan Design Code [(DFDC)](https://web.mit.edu/drela/Public/web/dfdc/), utilizing a linear axisymmetric vortex panel method for duct and center body, blade element lifting line rotor representation, and psuedo wake-screw wake model axisymmetrically smeared onto an elliptic grid for efficient computation. + +DuctAPE has been developed specifically for applications in gradient-based optimization settings. +The selected solver methods have been chosen to balance code efficiency as well as robustness while simultaneously allowing for efficient automatic differentiation through DuctAPE employing [ImplicitAD.jl](https://flow.byu.edu/ImplicitAD.jl/dev/). +At the same time, the basic functionality of a DFDC-like solve approach has been maintained for the interested user. + +## Package Features + +- + +## Installation + +As DuctAPE is not yet a registered package, if you have access to the development repository at this time you can add the package through Julia's package manager as: + +```julia +pkg> add "https://github.com/byuflowlab/DuctAPE.jl" +``` diff --git a/docs/src/theory.md b/docs/src/theory.md new file mode 100644 index 00000000..006f9c5d --- /dev/null +++ b/docs/src/theory.md @@ -0,0 +1 @@ +# Theory diff --git a/docs/src/tutorial.md b/docs/src/tutorial.md new file mode 100644 index 00000000..a7594309 --- /dev/null +++ b/docs/src/tutorial.md @@ -0,0 +1,364 @@ +# Getting Started + + +```@contents +Pages = ["tutorial.md"] +Depth = 5 +``` + +The following is a basic tutorial on how to set up the inputs to, and run an analysis of a ducted fan in DuctAPE. + +```@setup dfdc +include("../assets/plots_default.jl") +``` + +We begin by loading the package, and optionally create a shorthand name. + +```@example dfdc +using DuctAPE +const dt = DuctAPE +``` + +## Build Inputs + +The next step is to create the input object of type `Propulsor` + +```@docs +DuctAPE.Propulsor +``` + +### Body Geometry + +To do so, we begin by defining a matrix of coordinates for the duct and another for the centerbody geometries, for example: + +```@example dfdc +duct_coordinates = [ + 0.304466 0.158439 + 0.294972 0.158441 + 0.28113 0.158423 + 0.266505 0.158365 + 0.251898 0.158254 + 0.237332 0.158088 + 0.222751 0.157864 + 0.208123 0.157586 + 0.193399 0.157258 + 0.178507 0.156897 + 0.16349 0.156523 + 0.148679 0.156177 + 0.134222 0.155902 + 0.12 0.155721 + 0.106044 0.155585 + 0.092531 0.155498 + 0.079836 0.155546 + 0.067995 0.155792 + 0.057025 0.156294 + 0.046983 0.157103 + 0.037937 0.158256 + 0.029956 0.159771 + 0.02311 0.161648 + 0.017419 0.163862 + 0.012842 0.166404 + 0.009324 0.169289 + 0.006854 0.172546 + 0.005484 0.176154 + 0.005242 0.180005 + 0.006112 0.184067 + 0.00809 0.188086 + 0.011135 0.192004 + 0.015227 0.19579 + 0.020339 0.199393 + 0.026403 0.202735 + 0.033312 0.205736 + 0.040949 0.208332 + 0.049193 0.210487 + 0.057935 0.212174 + 0.067113 0.21339 + 0.076647 0.214136 + 0.086499 0.214421 + 0.09661 0.214255 + 0.10695 0.213649 + 0.117508 0.212618 + 0.12838 0.211153 + 0.139859 0.209267 + 0.151644 0.207051 + 0.163586 0.204547 + 0.175647 0.201771 + 0.187807 0.198746 + 0.20002 0.19549 + 0.212269 0.192017 + 0.224549 0.188335 + 0.236794 0.18447 + 0.249026 0.180416 + 0.261206 0.176188 + 0.273301 0.171796 + 0.28524 0.16727 + 0.29644 0.162842 + 0.304542 0.159526 +] +nothing # hide +``` + +```@example dfdc +centerbody_coordinates = [ + 0.0 0.0 + 0.000586 0.005293 + 0.002179 0.010047 + 0.004736 0.014551 + 0.008231 0.018825 + 0.012632 0.022848 + 0.01788 0.026585 + 0.023901 0.030001 + 0.030604 0.033068 + 0.0379 0.035771 + 0.045705 0.038107 + 0.053933 0.040075 + 0.06254 0.04169 + 0.071451 0.042966 + 0.08063 0.043916 + 0.090039 0.044561 + 0.09968 0.044922 + 0.109361 0.044999 + 0.12 0.044952 + 0.135773 0.04495 + 0.151899 0.04493 + 0.16806 0.044913 + 0.184232 0.044898 + 0.200407 0.044882 + 0.21658 0.044866 + 0.232723 0.044847 + 0.248578 0.044839 + 0.262095 0.044564 + 0.274184 0.043576 + 0.285768 0.041795 + 0.296701 0.039168 + 0.306379 0.035928 +] +nothing # hide +``` + +```@example dfdc +pg = plot(duct_coordinates[:,1], duct_coordinates[:,2], aspectratio=1, color=1, linewidth=2, label="Duct", xlabel="z", ylabel="r", legend=:left) # hide +plot!(pg, centerbody_coordinates[:,1], centerbody_coordinates[:,2], color=2, linewidth=2, label="Center Body") # hide +``` + +!!! note + The body geometry coordinates must be input as columns of z (axial) and r (radial) coordinates, in that order. + +### Rotor Geometry + +The next step is to assemble an object of type `RotorStatorParameters` which contains the geometric information required to define the rotor(s) and their respective blade elements. + +```@docs +DuctAPE.RotorStatorParameters +``` + +In this example, we have a single rotor defined as follows. + +```@example dfdc +B = 5 + +rotorzloc = 0.12 + +Rtip = 0.15572081487373543 + +Rhub = 0.04495252299071941 + +r = [ + 0.050491 + 0.061567 + 0.072644 + 0.083721 + 0.094798 + 0.10587 + 0.11695 + 0.12803 + 0.13911 + 0.15018 +]./Rtip + +chords = [ + 0.089142 + 0.079785 + 0.0713 + 0.063979 + 0.057777 + 0.052541 + 0.048103 + 0.044316 + 0.041061 + 0.038243 +] + +twists = [ + 69.012 + 59.142 + 51.825 + 46.272 + 41.952 + 38.509 + 35.699 + 33.354 + 31.349 + 29.596 +].*pi/180.0 + + +afparams = DuctAPE.c4b.DFDCairfoil(; + alpha0=0.0, + clmax=1.5, + clmin=-1.0, + dclda=6.28, + dclda_stall=0.5, + dcl_stall=0.2, + cdmin=0.012, + clcdmin=0.1, + dcddcl2=0.005, + cmcon=0.0, + Re_ref=2e5, + Re_exp=0.35, + mcrit=0.7, +) + +airfoils = fill(afparams, length(r)) # specify the airfoil array + +rotorstator_parameters = dt.RotorStatorParameters( + [B], + [rotorzloc], + r, + [Rhub], + [Rtip], + chords, + twists, + [0.0], # currently only zero tip gaps work. + airfoils, + [0.0], # can flip the cl lookups on the fly if desired, say, for stator sections +) +nothing # hide +``` + +```@example dfdc +plot!(pg, rotorzloc*ones(length(r)), r.*Rtip, seriestype=:scatter, markerstrokewidth=0, label="Blade Elements") # hide +``` + +!!! note "Airfoils" + Airfoil types for DuctAPE are currently contained in the C4Blade (Cascade Compatible [CCBlade](https://flow.byu.edu/CCBlade.jl/stable/)) sub-module of DuctAPE which is exported as `c4b` and also contains the various airfoil evaluation functions used for the blade element lookups. + The available airfoil types include all the airfoil types from CCBlade, as well as `DFDCairfoil` which is an [XROTOR](https://web.mit.edu/drela/Public/web/xrotor/)-like parametric cascade polar used in DFDC. + In addition there are untested cascade types with similar structure to CCBlades airfoil types called `DTCascade`. + +### Operating Point + +Next we will assemble the operating point which contains information about the freestream as well as the rotor rotation rate(s). + +```@docs +DuctAPE.OperatingPoint +``` + +```@example dfdc +# Freestream +Vinf = 0.0 # hover condition +rhoinf = 1.226 +asound = 340.0 +muinf = 1.78e-5 + +# Rotation Rate +RPM = 8000.0 +Omega = RPM * pi / 30 # if using RPM, be sure to convert to rad/s + +# utilizing the constructor function to put things in vector types +operating_point = dt.OperatingPoint(Vinf, rhoinf, muinf, asound, Omega) + +nothing # hide +``` + +### Paneling Constants + +The `PanelingConstants` object contains the constants required for DuctAPE to re-panel the provided geometry into a format compatible with the solve structure. +The `PanelingConstants` object is also used to build all of the preallocated caches inside DuctAPE, which can be done up-front if desired. +Note that there is some functionality in place for cases when the user wants to keep their own specified geometry, but this functionality should be used with caution and only by users who are certain their provided geometry is in the compatible format. See the examples for an example. + +```@docs +DuctAPE.PanelingConstants +``` + +```@example dfdc +nduct_inlet = 30 +ncenterbody_inlet = 30 +npanels = [30, 1, 30] # the 1 is due to the fact that the duct and center body trailing edges are not quite aligned. +dte_minus_cbte = -1.0 # the duct trailing edge is ahead of the centerbody trailing edge. +nwake_sheets = 11 +wake_length = 0.8 + +paneling_constants = dt.PanelingConstants( + nduct_inlet, ncenterbody_inlet, npanels, dte_minus_cbte, nwake_sheets, wake_length +) +nothing # hide +``` + +### Reference Parameters + +The reference parameters are used in the post-processing non-dimensionalizations. + +```@docs +DuctAPE.ReferenceParameters +``` + +```@example dfdc +Vref = 50.0 #this turns out to be close to the average axial velocity at the rotor in our case +Rref = Rtip + +reference_parameters = dt.ReferenceParameters([Vref], [Rref]) +nothing # hide +``` + +### All Together + +We are now posed to construct the `Propulsor` input type. + +```@example dfdc +propulsor = dt.Propulsor( + duct_coordinates, + centerbody_coordinates, + rotorstator_parameters, + operating_point, + paneling_constants, + reference_parameters, +) +nothing # hide +``` + +## Set Options + +The default options should be sufficient for just starting out and are set through the `set_options` function. + +```@docs +DuctAPE.set_options +``` + +```@example dfdc +options = dt.set_options() +``` + +For more advanced option selection, see the examples and API reference. + +## Run Analysis + +With the propulsor input build, and the options selected, we are now ready to run an analysis. +This is done simply with the `analyze` function which dispatches the appropriate analysis, solve, and post-processing functions based on the selected options. + +```@example dfdc +outs, success_flag = dt.analyze(propulsor, options) +nothing # hide +``` + +## Outputs + +There are many outputs contained in the named tuple output from the `analyze` function (see the examples), but some that may be of immediate interest include: + +```@example dfdc +# Total Thrust Coefficient +outs.totals.CT +``` +```@example dfdc +# Total Torque Coefficient +outs.totals.CQ +```