tadd docstrings to all functions - Granular.jl - Julia package for granular dyn… | |
git clone git://src.adamsgaard.dk/Granular.jl | |
Log | |
Files | |
Refs | |
README | |
LICENSE | |
--- | |
commit aa49a17a7ce969f67b58e7f4196f65a48a5f0e5c | |
parent 5b777d9bdb78d24eab9387b0ab15e99ba074737f | |
Author: Anders Damsgaard <[email protected]> | |
Date: Thu, 20 Apr 2017 15:51:52 -0400 | |
add docstrings to all functions | |
Diffstat: | |
M src/SeaIce.jl | 25 +++++-------------------- | |
D src/arrays.jl | 1 - | |
M src/contact_search.jl | 7 +++++++ | |
M src/datatypes.jl | 1 - | |
M src/interaction.jl | 4 ++++ | |
M src/io.jl | 5 +++++ | |
M src/simulation.jl | 67 ++++++++++++++++++++++++++++-… | |
M src/temporal.jl | 27 +++++++++++++++++++++++++-- | |
M src/temporal_integration.jl | 18 +++++++++++++++++- | |
M test/contact-search-and-geometry.jl | 4 ++-- | |
10 files changed, 126 insertions(+), 33 deletions(-) | |
--- | |
diff --git a/src/SeaIce.jl b/src/SeaIce.jl | |
t@@ -1,30 +1,15 @@ | |
#!/usr/bin/env julia | |
-############################## | |
-# Sea-ice dynamics simulator # | |
-############################## | |
- | |
-#= | |
-Add SeaIce to your julia path, e.g. by: | |
- push!(LOAD_PATH, "/home/user/src/seaice/") | |
- | |
-If this statement is added to `~/.juliarc.jl`, it will become persistent betwe… | |
-julia sessions. Note that the `~` symbol for the home folder does not seem to | |
-work (julia v. 0.4.1) in the `.juliarc.jl` file. | |
- | |
-Import package contents with: | |
- import SeaIce | |
- | |
-If this file is changed, reimport it with: | |
- reload("SeaIce") | |
-=# | |
- | |
+""" | |
+# SeaIce.jl | |
+Offline sea-ice dynamics simulator by [Anders Damsgaard](mailto:andersd@riseup… | |
+[www.adamsgaard.dk](https://adamsgaard.dk) | |
+""" | |
module SeaIce | |
include("datatypes.jl") | |
include("icefloe.jl") | |
include("simulation.jl") | |
-include("arrays.jl") | |
include("grid.jl") | |
include("packing.jl") | |
include("contact_search.jl") | |
diff --git a/src/arrays.jl b/src/arrays.jl | |
t@@ -1 +0,0 @@ | |
-## Global arrays for general simulation data | |
diff --git a/src/contact_search.jl b/src/contact_search.jl | |
t@@ -1,4 +1,11 @@ | |
## Contact mapping | |
+""" | |
+Top-level function to perform an inter-ice floe contact search, based on ice | |
+floe linear positions and contact radii. | |
+ | |
+The simplest contact search algorithm (`method="all to all"`) is the most | |
+computationally expensive (O(n^2)). | |
+""" | |
function findContacts!(simulation::Simulation, | |
method::String = "all to all") | |
diff --git a/src/datatypes.jl b/src/datatypes.jl | |
t@@ -3,7 +3,6 @@ const float = Float64 | |
const vector = Array{Float64, 1} | |
## Particle composite types | |
- | |
type IceFloeCylindrical | |
# Material properties | |
diff --git a/src/interaction.jl b/src/interaction.jl | |
t@@ -45,6 +45,10 @@ function interactIceFloes!(simulation::Simulation, | |
end | |
+""" | |
+Resolves linear-elastic interaction between two ice floes in the contact-norma… | |
+direction. | |
+""" | |
function interactNormalLinearElastic(simulation::Simulation, | |
i::Integer, j::Integer, | |
overlap_vector::vector) | |
diff --git a/src/io.jl b/src/io.jl | |
t@@ -2,6 +2,11 @@ import WriteVTK # Install with Pkg.add("WriteVTK") | |
## IO functions | |
+""" | |
+Write a VTK file to disk containing all ice floes in the `simulation` in an | |
+unstructured mesh (file type `.vtu`). These files can be read by ParaView and | |
+can be visualized by applying a *Glyph* filter. | |
+""" | |
function writeVTK(simulation::Simulation; | |
folder::String=".", | |
verbose::Bool=false) | |
diff --git a/src/simulation.jl b/src/simulation.jl | |
t@@ -1,5 +1,24 @@ | |
## General simulation functions | |
+""" | |
+ createSimulation([id::String="unnamed", | |
+ time_iteration::Int=0, | |
+ time::Float64=0.0, | |
+ time_total::Float64=-1., | |
+ time_step::Float64=-1., | |
+ file_time_step::Float64=-1., | |
+ file_number::Int=0, | |
+ ice_floes=Array{IceFloeCylindrical, 1}[], | |
+ contact_pairs=Array{Int64, 1}[], | |
+ overlaps=Array{Array{Float64, 1}, 1}[], | |
+ wall_contacts=Array{Int64, 1}[]]) | |
+ | |
+Create a simulation object containing all relevant variables such as temporal | |
+parameters, and lists of ice floes and contacts. | |
+ | |
+The parameter `id` is used to uniquely identify the simulation when it is | |
+written to disk. | |
+""" | |
function createSimulation(;id::String="unnamed", | |
time_iteration::Int=0, | |
time::Float64=0.0, | |
t@@ -25,12 +44,43 @@ function createSimulation(;id::String="unnamed", | |
wall_contacts) | |
end | |
+""" | |
+ run!(simulation[, | |
+ verbose::Bool = true, | |
+ status_interval = 100., | |
+ show_file_output = true, | |
+ single_step=false, | |
+ temporal_integration_method="Three-term Taylor"]) | |
+ | |
+Run the `simulation` through time until `simulation.time` equals or exceeds | |
+`simulatim.time_total`. This function requires that all ice floes are added t… | |
+the simulation and that the length of the computational time step is adjusted | |
+accordingly. | |
+ | |
+The function will search for contacts, determine the force balance on each ice | |
+floe, and integrate all kinematic degrees of freedom accordingly. The tempora… | |
+integration is explicit and of length `simulation.time_step`. This function | |
+will write VTK files to disk in the intervals `simulation.file_time_step` by t… | |
+function `writeVTK`. If this value is negative, no output files will be writt… | |
+to disk. | |
+ | |
+# Arguments | |
+* `simulation::Simulation`: the simulation to run (object is modified) | |
+* `verbose::Bool=true`: show verbose information during the time loop | |
+* `status_interval::Bool=true`: show verbose information during the time loop | |
+* `show_file_output::Bool=true`: report to stdout when output file is written | |
+* `single_step::Bool=false`: run simulation for a single time step only. If | |
+ this causes `simulation.time` to exceed `simulation.time_total`, the latte… | |
+ is increased accordingly. | |
+* `temporal_integration_method::String="Three-term Taylor"`: type of integrati… | |
+ method to use. See `updateIceFloeKinematics` for details. | |
+""" | |
function run!(simulation::Simulation; | |
- verbose::Bool = true, | |
- status_interval = 100., | |
- show_file_output = true, | |
- single_step=false, | |
- temporal_integration_method="Three-term Taylor") | |
+ verbose::Bool=true, | |
+ status_interval::Int=100., | |
+ show_file_output::Bool=true, | |
+ single_step::Bool=false, | |
+ temporal_integration_method::String="Three-term Taylor") | |
if single_step && simulation.time >= simulation.time_total | |
simulation.time_total += simulation.time_step | |
t@@ -63,7 +113,7 @@ function run!(simulation::Simulation; | |
# Update time variables | |
simulation.time_iteration += 1 | |
- simulation.time += simulation.time_step | |
+ incrementCurrentTime(simulation, simulation.time_step) | |
time_since_output_file = time_since_output_file + simulation.time_step | |
if single_step | |
t@@ -79,6 +129,8 @@ function run!(simulation::Simulation; | |
end | |
end | |
+"Add an `icefloe` to the `simulation` object. If `verbose` is true, a short | |
+confirmation message will be printed to stdout`." | |
function addIceFloe!(simulation::Simulation, | |
icefloe::IceFloeCylindrical, | |
verbose::Bool = False) | |
t@@ -90,6 +142,7 @@ function addIceFloe!(simulation::Simulation, | |
end | |
end | |
+"Remove ice floe with index `i` from the `simulation` object." | |
function removeIceFloe!(simulation::Simulation, i::Integer) | |
if i < 1 | |
error("Index must be greater than 0 (i = $i)") | |
t@@ -98,6 +151,7 @@ function removeIceFloe!(simulation::Simulation, i::Integer) | |
delete!(simulation.ice_floes, i) | |
end | |
+"Sets the `force` and `torque` values of all ice floes to zero." | |
function zeroForcesAndTorques!(simulation::Simulation) | |
for icefloe in simulation.ice_floes | |
icefloe.force = zeros(2) | |
t@@ -105,6 +159,7 @@ function zeroForcesAndTorques!(simulation::Simulation) | |
end | |
end | |
+"Prints the current simulation time and total time to standard out" | |
function reportSimulationTimeToStdout(simulation::Simulation) | |
print("\r t = ", simulation.time, '/', simulation.time_total, | |
" s ") | |
diff --git a/src/temporal.jl b/src/temporal.jl | |
t@@ -1,4 +1,9 @@ | |
-## Set temporal parameters | |
+""" | |
+ setTotalTime!(simulation::Simulation, t::float) | |
+ | |
+Sets the total simulation time of the `simulation` object to `t`, with paramet… | |
+value checks. | |
+""" | |
function setTotalTime!(simulation::Simulation, t::float) | |
if t <= 0.0 | |
error("Total time should be a positive value (t = $t s)") | |
t@@ -6,6 +11,12 @@ function setTotalTime!(simulation::Simulation, t::float) | |
simulation.time_total = t | |
end | |
+""" | |
+ setCurrentTime!(simulation::Simulation, t::float) | |
+ | |
+Sets the current simulation time of the `simulation` object to `t`, with | |
+parameter value checks. | |
+""" | |
function setCurrentTime!(simulation::Simulation, t::float) | |
if t <= 0.0 | |
error("Current time should be a positive value (t = $t s)") | |
t@@ -13,11 +24,17 @@ function setCurrentTime!(simulation::Simulation, t::float) | |
simulation.time = t | |
end | |
+""" | |
+ incrementCurrentTime!(simulation::Simulation, t::float) | |
+ | |
+Sets the current simulation time of the `simulation` object to `t`, with | |
+parameter value checks. | |
+""" | |
function incrementCurrentTime!(simulation::Simulation, t::float) | |
if t <= 0.0 | |
error("Current time increment should be a positive value (t = $t s)") | |
end | |
- simulation.time = simulation.time + t | |
+ simulation.time += t | |
end | |
function setOutputFileInterval!(simulation::Simulation, t::float) | |
t@@ -27,10 +44,12 @@ function setOutputFileInterval!(simulation::Simulation, t:… | |
simulation.file_time_step = t | |
end | |
+"Disables the write of output files to disk during a simulation." | |
function disableOutputFiles!(simulation::Simulation) | |
simulation.file_time_step = 0.0 | |
end | |
+"Checks if simulation parameters are of reasonable values." | |
function checkTimeParameters(simulation::Simulation) | |
if simulation.time_total <= 0.0 || simulation.time_total <= simulation.time | |
error("Total time should be positive and larger than current time.\n", | |
t@@ -42,6 +61,8 @@ function checkTimeParameters(simulation::Simulation) | |
end | |
end | |
+"Finds the smallest mass of all ice floes in a simulation. Used to determine | |
+the optimal time step length." | |
function findSmallestIceFloeMass(simulation::Simulation) | |
m_min = 1e20 | |
i_min = -1 | |
t@@ -55,6 +76,8 @@ function findSmallestIceFloeMass(simulation::Simulation) | |
return m_min, i_min | |
end | |
+"Finds the largest elastic stiffness of all ice floes in a simulation. Used t… | |
+determine the optimal time step length." | |
function findLargestIceFloeStiffness(simulation::Simulation) | |
k_n_max = 0. | |
k_t_max = 0. | |
diff --git a/src/temporal_integration.jl b/src/temporal_integration.jl | |
t@@ -1,6 +1,19 @@ | |
""" | |
+ updateIceFloeKinematics!(simulation::Simulation[, | |
+ method::String = "Three-term Taylor"]) | |
+ | |
Update the ice floe kinematic parameters using a temporal integration scheme, | |
the current force and torque balance, and gravitational acceleration. | |
+ | |
+# Arguments | |
+* `simulation::Simulation`: update the ice floe positions in this object | |
+ according to temporal integration of length `simulation.time_step`. | |
+* `method::String = "Three-term Taylor"`: the integration method to use. | |
+ Available methods are "Two-term Taylor" and "Three-term Taylor". The | |
+ three-term Taylor expansion is slightly more computationally expensive tha… | |
+ the two-term Taylor expansion, but offers an order-of-magnitude increase i… | |
+ precision of ice floe positions. The two-term expansion can obtain simila… | |
+ precision if the time step is 1/10 the length. | |
""" | |
function updateIceFloeKinematics!(simulation::Simulation; | |
method::String = "Three-term Taylor") | |
t@@ -18,6 +31,8 @@ function updateIceFloeKinematics!(simulation::Simulation; | |
end | |
end | |
+"Use a two-term Taylor expansion for integrating the kinematic degrees of | |
+freedom for an `icefloe`." | |
function updateIceFloeKinematicsTwoTermTaylor(icefloe::IceFloeCylindrical, | |
simulation::Simulation) | |
icefloe.lin_acc = icefloe.force/icefloe.mass | |
t@@ -41,6 +56,8 @@ function updateIceFloeKinematicsTwoTermTaylor(icefloe::IceFl… | |
icefloe.ang_vel += icefloe.ang_acc * simulation.time_step | |
end | |
+"Use a three-term Taylor expansion for integrating the kinematic degrees of | |
+freedom for an `icefloe`." | |
function updateIceFloeKinematicsThreeTermTaylor(icefloe::IceFloeCylindrical, | |
simulation::Simulation) | |
t@@ -80,4 +97,3 @@ function updateIceFloeKinematicsThreeTermTaylor(icefloe::Ice… | |
icefloe.ang_vel += icefloe.ang_acc * simulation.time_step + | |
0.5 * d_ang_acc_dt * simulation.time_step^2. | |
end | |
- | |
diff --git a/test/contact-search-and-geometry.jl b/test/contact-search-and-geom… | |
t@@ -14,8 +14,8 @@ SeaIce.addIceFloeCylindrical(sim, [18., 0.], 10., 1., verbos… | |
position_ij = SeaIce.interIceFloePositionVector(sim, 1, 2) | |
overlap_ij = SeaIce.findOverlap(sim, 1, 2, position_ij) | |
-Base.Test.@test_approx_eq [18., 0.] position_ij | |
-Base.Test.@test_approx_eq -2. overlap_ij | |
+Base.Test.@test [18., 0.] \approx position_ij | |
+Base.Test.@test -2. \approx overlap_ij | |
info("Testing findContactsAllToAll(...)") |