tfix docstrings and Simulation object creation - Granular.jl - Julia package for granular dynamics simulation
(HTM) git clone git://src.adamsgaard.dk/Granular.jl
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
(DIR) commit a9d41bf6abc198818ed79d3ff76f9be05bd9a80b
(DIR) parent f99ed0c1563094ca59a039ab144b9da3e76c1fed
(HTM) Author: Anders Damsgaard <andersd@riseup.net>
Date: Tue, 14 Nov 2017 12:10:42 -0500
fix docstrings and Simulation object creation
Diffstat:
M docs/src/man/getting_started.md | 24 ++++++++++++------------
M src/Granular.jl | 1 +
M src/simulation.jl | 60 +++++++++++++++----------------
M src/wall.jl | 18 +++++++++++++-----
M test/wall.jl | 9 ++++++++-
5 files changed, 63 insertions(+), 49 deletions(-)
---
(DIR) diff --git a/docs/src/man/getting_started.md b/docs/src/man/getting_started.md
t@@ -22,20 +22,20 @@ online documentation, or simply from the Julia shell by typing `?<function
name>`. An example:
```julia-repl
-julia> ?Granular.fitGridToGrains!
+julia> ?Granular.createSimulation
+ createSimulation([id::String="unnamed"])
- fitGridToGrains!(simulation, grid[, padding, verbose])
+ Create a simulation object to contain all relevant variables such as temporal
+ parameters, fluid grids, grains, and contacts. The parameter id is used to
+ uniquely identify the simulation when it is written to disk.
- Fit the ocean or atmosphere grid for a simulation to the current grains and
- their positions.
+ The function returns a Simulation object, which you can add grains to, e.g.
+ with addGrainCylindrical!.
- Arguments
- ≡≡≡≡≡≡≡≡≡≡≡
+ Optional argument
+ ≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡
- • simulation::Simulation: simulation object to manipulate.
- • grid::Any: Ocean or Atmosphere grid to manipulate.
- • padding::Real: optional padding around edges [m].
- • verbose::Bool: show grid information when function completes.
+ • id::String="unnamed": simulation identifying string.
```
You can go through the examples below by typing in the lines starting with
t@@ -85,8 +85,8 @@ the following commands. Next, we can add grains to this object. The first
grain is cylinder shaped, placed at the x-y position (0,0) m. It has a radius
of 0.1 m, and has a thickness of 0.05 m. As this call modifies the `sim`
object, the function contains an exclamation mark (!). For further information
-regarding this call, see the reference in the [Public API Index](@ref
-main-index).
+regarding this call, see the reference to [`addGrainCylindrical!`](@ref), found
+in the [Public API documentation](@ref).
```julia-repl
julia> Granular.addGrainCylindrical!(sim, [0.0, 0.0], 0.1, 0.05)
(DIR) diff --git a/src/Granular.jl b/src/Granular.jl
t@@ -19,5 +19,6 @@ include("io.jl")
include("ocean.jl")
include("atmosphere.jl")
include("util.jl")
+include("wall.jl")
end # module end
(DIR) diff --git a/src/simulation.jl b/src/simulation.jl
t@@ -2,39 +2,36 @@
export createSimulation
"""
- 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,
- grains=Array{GrainCylindrical, 1}[],
- ocean::Ocean,
- atmosphere::Atmosphere,
- Nc_max::Int=16])
-
-Create a simulation object containing all relevant variables such as temporal
-parameters, fluid grids, grains, and contacts. All arguments are optional. The
-most important parameter is `id`, which is used to uniquely identify the
-simulation when it is written to disk.
-
-# Optional arguments
+ createSimulation([id::String="unnamed"])
+
+Create a simulation object to contain all relevant variables such as temporal
+parameters, fluid grids, grains, and contacts. The parameter `id` is used to
+uniquely identify the simulation when it is written to disk.
+
+The function returns a `Simulation` object, which you can add grains to, e.g.
+with [`addGrainCylindrical!`](@ref).
+
+# Optional argument
* `id::String="unnamed"`: simulation identifying string.
"""
-function 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,
- file_time_since_output_file::Float64=0.,
- grains=Array{GrainCylindrical, 1}[],
- ocean::Ocean=createEmptyOcean(),
- atmosphere::Atmosphere=createEmptyAtmosphere(),
- Nc_max::Int=16)
+function createSimulation(;id::String="unnamed")
+
+ # default values for simulation parameters (not included as arguments as
+ # they are very rarely chagned and make the docstring much more cluttered
+ # and intimidating
+ 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
+ file_time_since_output_file::Float64 = 0.
+ grains = Array{GrainCylindrical, 1}[]
+ ocean::Ocean = createEmptyOcean()
+ atmosphere::Atmosphere = createEmptyAtmosphere()
+ Nc_max::Int = 16
+ walls = Array{WallLinearFrictionless, 1}[]
return Simulation(id,
time_iteration,
t@@ -47,7 +44,8 @@ function createSimulation(;id::String="unnamed",
grains,
ocean,
atmosphere,
- Nc_max)
+ Nc_max,
+ walls)
end
export run!
(DIR) diff --git a/src/wall.jl b/src/wall.jl
t@@ -70,7 +70,7 @@ function addWallLinearFrictionless!(simulation::Simulation,
normal_stress::Float64 = 0.,
vel::Float64 = 0.,
force::Float64 = 0.,
- verbose::Boolw=true)
+ verbose::Bool=true)
# Check input values
if length(normal) != 2
t@@ -78,17 +78,21 @@ function addWallLinearFrictionless!(simulation::Simulation,
"$normal)")
end
- if !(normal ≈ [1., 0.]) || !(normal ≈ [0., 1.])
+ if !(normal ≈ [1., 0.]) && !(normal ≈ [0., 1.])
error("Currently only walls with normals orthogonal to the " *
"coordinate system are allowed, i.e. normals parallel to the " *
"x or y axes. Accepted values for `normal` " *
- "are [1., 0.] and [0., 1.]")
+ "are [1., 0.] and [0., 1.]. The passed normal was $normal")
end
# if not set, set wall mass to equal the mass of all grains.
if isnan(mass)
+ if length(simulation.grains < 1)
+ error("If wall mass is not specified, walls should be added " *
+ "after grains have been added to the simulation.")
+ end
mass = 0.
- for grain in sim.grains
+ for grain in simulation.grains
mass += grain.mass
end
info("Setting wall mass to total grain mass: $mass kg")
t@@ -96,8 +100,12 @@ function addWallLinearFrictionless!(simulation::Simulation,
# if not set, set wall thickness to equal largest grain thickness
if isnan(thickness)
+ if length(simulation.grains < 1)
+ error("If wall thickness is not specified, walls should be added " *
+ "after grains have been added to the simulation.")
+ end
thickness = -Inf
- for grain in sim.grains
+ for grain in simulation.grains
if grain.thickess > thickness
thickness = grain.thickness
end
(DIR) diff --git a/test/wall.jl b/test/wall.jl
t@@ -4,14 +4,21 @@
info("#### $(basename(@__FILE__)) ####")
+info("Testing argument value checks")
sim = Granular.createSimulation(id="test")
-info("Testing grain value checks ")
+Granular.addGrainCylindrical!(sim, [ 0., 0.], 10., 2., verbose=false)
@test_throws ErrorException Granular.addWallLinearFrictionless!(sim,
[.1, .1, .1],
1.)
@test_throws ErrorException Granular.addWallLinearFrictionless!(sim,
[1., 1.],
1.)
+@test_throws ErrorException Granular.addWallLinearFrictionless!(sim,
+ [.1, .1, .1],
+ 1.)
+sim = Granular.createSimulation(id="test")
+@test_throws ErrorException Granular.addWallLinearFrictionless!(sim, [1., 0.],
+ 1.)
info("Check that wall mass equals total grain mass and max. thickness")