Skip to content

Refactoring docs #840

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
kmruehl merged 9 commits into from
Apr 20, 2022
Merged

Refactoring docs #840

kmruehl merged 9 commits into from
Apr 20, 2022

Conversation

@kmruehl
Copy link
Collaborator

@kmruehl kmruehl commented Mar 29, 2022

This PR is a continuation of #803 and #822 and #828 and #832

Objectives:

  • clear and intuitive variable naming using camelCase
  • consistent properties across classes, e.g. pto.loc versus mooring.ref
  • convert properties for a single feature to property structures, e.g. struct(body.morison)
  • move properties to the appropriate class, e.g. simu.yaw to body.yaw
  • updating WEC-Sim library accordingly

@kmruehl kmruehl added the Documentation related to docs label Mar 29, 2022
@kmruehl
Copy link
Collaborator Author

kmruehl commented Mar 29, 2022 •
edited
Loading

Documentation refactoring updates

by @kmruehl

Wave Class

  • waves.etaImport to waves.waveImport to waves.elevationImport
  • waves.spectrumDataFile to waves.waveSpectrumFile to waves.spectrumFile
  • waves.etaDataFile to waves.waveElevationFileto waves.elevationFile
  • waves.plotEta to waves.plotElevation
  • waves.waveDir to waves.waveDirection to waves.direction
  • waves.waveSpread to waves.spread
  • beta to theta to match online documentation
  • waves.deepWaterWave to waves.deepWater
  • convert waves.current properties to structure, similar to morison element,
    • waves.currentOption to waves.current.option
    • waves.currentDepth to waves.current.depth
    • waves.currentDirection to waves.current.direction
    • waves.currentSpeed to waves.current.speed
  • convert properties related to BEM data to waves.bem structure
    • waves.numFreq to waves.freqNum to waves.bem.count
    • waves.freqDisc to waves.bem.option
    • waves.freqRange to wave.bem.range
  • add checks for waveClass structures
  • convert waves.marker properties to structure
    • waves.markerLoc to waves.marker.loc to waves.marker.location
    • waves.markerSize to waves.marker.size
    • waves.markerStyle to waves.marker.style
    • convert waves.marker properties to structure in Frames Library
  • waves.T to waves.period
  • waves.H to waves.height
  • waves.A to waves.amplitude
  • waves.S to waves.spectrum
  • waves.Pw to waves.power
  • waves.w to waves.omega
  • waves.dw to waves.dOmega
  • waves.k to waves.wavenumber

Simulation Class

  • simu.writetxt to simu.writeText to simu.saveText
  • waves.waveStatisticsDataLoad to simu.mcrExcelFile (formerly Wave Class)
  • simu.mcrCaseFile to simu.mcrMatFile
  • simu.dtME to simu.morisonDt
  • simu.CTTime to simu.cicTime
  • simu.dtCI to simu.cicDt
  • simu.CITime to simu.cicEndTime
  • simu.CIkt to simu.cicLength
  • simu.ssCalc to simu.stateSpace
  • simu.setupSimu to simu.simuSetup to simu.setup
  • convert simu.paraview properties to structure, similar to morison element, note: test that sub-properties are tested
    • simu.dtParaview to simu.paraviewDt to simu.paraview.dt
    • simu.StartTimeParaview to simu.paraviewStartTime to simu.paraview.startTime
    • simu.EndTimeParaview to simu.paraviewEndTime to simu.paraview.endTime
    • simu.pathParaviewVideo to simu.paraviewDirectory to simu.paraview.path
  • simu.numWecBodies to simu.body.numHydroBodies
  • simu.pressureDis to simu.pressure
  • simu.simulationDate to simu.date
  • add checks for simulationClass structures
  • simu.adjMassWeightFun to simu.adjMassFactor
  • simu.autoRateTranBlk to simu.rateTransition
  • simu.zeroCrossCont to simu.zeroCross
  • simu.numIntMidTimeSteps removed
  • parallelComputing_dir to pctDir NOTE this is not in the simulationClass, but maybe it should be
  • simu.g to simu.gravity

Body Class

  • body.dof_start to body.dofStart
  • body.dof_end to body.dofEnd
  • body.dof_gbm to body.dofGBM to body.gbmDOF
  • body.nlHydro to body.nonlinearHydro
  • body.lenJ to body.dofCoupled to body.b2bDOF
  • body.meanDriftForce to body.meanDrift
  • body.bodyparaview to body.paraviewBody to body.paraview
  • body.flexHydroBody to body.flexBody to body.flex
  • body.nhBody to body.nonHydroBody to body.nonHydro
  • body.hydroDataBodyNum to body.hydroBodyTotal to body.hydroTotal NOTE Do we even use this?
  • body.viscDrag to body.viscousDrag to body.quadDrag
  • body.userDefinedExcIRF to body.excitationIRF
  • add checks for bodyClass structures
  • move simu.yaw and simu.yawThresh to bodyClass
    • simu.yaw to body.yaw.option
    • simu.yawThres to body.yaw.threshold
  • body.bodyNumber to body.number
  • body.bodyTotal to body.total
  • body.bodyGeometry to body.geometry
    from @nathanmtom
  • quadDrag.Drag to quadDrag.drag
  • morisonElement.characteristicArea to morisonElement.area
  • quadDrag.characteristicArea to quadDrag.area
  • dispVol to displacedVolume to volume
  • body.initDisp.initLinDisp to body.initDisp.initLinearDisp to body.initial.displacement
  • body.initDisp.initAngularDispAngle to body.initial.angle
  • body.initDisp.initAngularDispAxis to body.initial.axis
  • cg to centerGravity
  • cb to centerBuoyancy
  • momOfInertia to intertia

Cable Class

  • cable.c to cable.damping
  • cable.k to cable.stiffness
  • cable.viscDrag to cable.viscousDrag to cable.quadDrag
  • cable.cableNum to cable.number
  • cable.loc to cable.location
    from @nathanmtom
  • cable.dispVol to cable.displacedVolume to cable.volume
  • cable.quadDrag.characteristicArea to quadDrag.area
  • cable.quadDrag.Drag to quadDrag.drag
  • cable.initDisp.initLinDisp to cable.initDisp.initLinearDisp to cable.initial.displacement
  • cable.initDisp.initAngularDispAngle to cable.initial.angle
  • cable.initDisp.initAngularDispAxis to cable.initial.axis
  • cable.L0 to cable.unstretchedLength tp cable.length
  • cable.bodyMass to cable.mass
  • cable.bodyInertia to cable.momOfInertia to cable.intertia
  • convert to cable.base and cable.follower structure
    • cable.cb1 to cable.centerBuoyancyBase to cable.baseCb to cable.base.centerBuoyancy
    • cable.cg1 to cable.centerGravityBase to cable.baseCg to cable.base.centerGravity
    • cable.rotloc1 to cable.rotationLocation1 to cable.baseLocation to to cable.base.location
    • cable.baseConnectionName to cable.base.name
    • cable.cb2 to cable.centerBuoyancyFollower to cable.followerCb to cable.follower.centerBuoyancy
    • cable.cg2 to cable.centerGravityFollower to cable.followerCg to cable.follower.centerGravity
    • cable.rotloc2 to cable.rotationLocation2 to cable.followerLocation to cable.follower.location
    • cable.followerConnectionName to cable.follower.name

Constraint Class

  • constraint.loc to constraint.location
  • constraint.constraintNum to constraint.number
    from @nathanmtom
  • constraint.initDisp.initLinDisp to constraint.initDisp.initLinearDisp to constraint..initial.displacement

PTO Class

  • pto.loc to pto.location
  • pto.c to pto.damping
  • pto.k to pto.stiffness
  • pto.ptoNum to pto.number
    from @nathanmtom
  • pto.initDisp.initLinDisp to pto.initDisp.initLinearDisp to pto.initial.displacement

Mooring Class

  • mooring.ref to mooring.loc to mooring.location
  • mooring.loc to mooring.orientation (internal)
  • mooring.mooringNum to mooring.number
    from @nathanmtom
  • mooring.initDisp.initLinDisp to mooring.initDisp.initLinearDisp to mooring.initial.displacement
  • mooring.initDisp.initAngularDispAngle to mooring.initial.angle
  • mooring.initDisp.initAngularDispAxis to mooring.initial.axis

Source/Functions/BEMIO

  • waveNumber to calcWaveNumber
  • spectralMoment to calcSpectralMoment

@kmruehl
Copy link
Collaborator Author

kmruehl commented Mar 29, 2022 •
edited
Loading

Remaining tasks from #832 (comment)

Help / documentation:
Refer to https://github.com/WEC-Sim/WEC-Sim/projects/58#card-79798675

  • update all classes now that properties and methods have changed, refer to Refactoring docs #840 (comment)
  • We should review formatting docstrings for class structures. Right now the API doesn't include line breaks, making the list of information hard to read, and the help and doc functions don't list all the necessary information. When using doc XClass the class constructor only lists the first line of the docstring. "Parameters" and "Returns" are not shown in the matlab docs. The API (usually) builds this description correctly. This doesn't seem to be an issue with other class methods. @akeeste
    • 3 distinct use cases: doc/help/API

Later:

  • add dev documentation for style guide, look into naming convention, e.g. pep 8 @kmruehl
  • add doc for refactored variables @kmruehl

Other Comments

  • Side comment here, but outside of it being difficult to maintain, it does seem like having a list of all variables in a table and every location they are used would be valuable to make similar changes in the future. Also, this allows to double check if a variable is actually used or not. I would appreciate some thoughts on if the team can think of a good method for this. --> moved to project board

@kmruehl kmruehl requested review from akeeste and nathanmtom March 29, 2022 22:29
@kmruehl
Copy link
Collaborator Author

kmruehl commented Mar 31, 2022

@akeeste when you're done with the doc updates, please mark the task complete above. Thanks!

@akeeste
Copy link
Contributor

akeeste commented Mar 31, 2022

@kmruehl I made a few updates to the doc strings. I was primarily hoping to find a way to get the doc and API to build documentation for class structures with line breaks so that the formatting is more organized like this:
image

and less like this:
image

However I could not find a way to do this. I think our formatting is best given how the API and doc works.

@kmruehl
Copy link
Collaborator Author

kmruehl commented Apr 20, 2022

I'm going to go ahead and merge this and we can figure out where to put the refactoring once v5.0 is released

@kmruehl kmruehl merged commit 3e34dd3 into WEC-Sim:dev Apr 20, 2022
@kmruehl kmruehl deleted the refactoring_docs branch April 20, 2022 17:23
@nathanmtom nathanmtom mentioned this pull request Apr 21, 2022
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@akeeste akeeste Awaiting requested review from akeeste

@nathanmtom nathanmtom Awaiting requested review from nathanmtom

Assignees

No one assigned

Labels

Documentation related to docs

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@kmruehl @akeeste