API
Index
UltraDark.Config
UltraDark.Output
UltraDark.Summary
UltraDark.AbstractGrids
UltraDark.Config.SimulationConfig
UltraDark.Config.TimeStepOptions
UltraDark.Config.TimeStepOptions
UltraDark.Grids
UltraDark.Output.OutputConfig
UltraDark.Output.OutputConfig
UltraDark.PencilGrids
UltraDark.Summary.AngularMomentum
UltraDark.Summary.EnergyGravity
UltraDark.Summary.EnergyKineticQuantum
UltraDark.Summary.MaxDensity
UltraDark.Summary.MaxDensityIndex
UltraDark.Summary.MeanDensity
UltraDark.Summary.RmsDensityContrast
UltraDark.Summary.ScaleFactor
UltraDark.Summary.SimulationTime
UltraDark.Summary.TimeStep
UltraDark.Summary.TotalMass
UltraDark.Summary.WallTime
UltraDark.Config.constant_scale_factor
UltraDark.E_grav
UltraDark.E_gravity_density
UltraDark.E_kq
UltraDark.E_total
UltraDark.Initialise.add_fdm_soliton!
UltraDark.Output.output_external_state
UltraDark.Output.output_external_state_header
UltraDark.Output.output_external_states_headers
UltraDark.Output.output_grids
UltraDark.Output.output_output_times
UltraDark.Output.output_state
UltraDark.Output.output_xyz
UltraDark.Summary.column_title
UltraDark.Summary.column_titles
UltraDark.Summary.generate_summary_row
UltraDark.Summary.get_relevant_data
UltraDark.Summary.map_summary_statistics
UltraDark.Summary.output_summary_header
UltraDark.Summary.output_summary_row
UltraDark.Summary.pool_summarystat
UltraDark.Summary.pool_summarystat
UltraDark.Summary.pool_summarystat
UltraDark.Summary.pool_summarystat
UltraDark.Summary.pool_summarystat
UltraDark.Summary.pool_summarystat
UltraDark.Summary.pool_summarystat
UltraDark.Summary.pool_summarystat
UltraDark.actual_time_step
UltraDark.add_external_potential!
UltraDark.angular_momentum
UltraDark.angular_momentum_density
UltraDark.auxiliary_step!
UltraDark.azimuthal_angle
UltraDark.dV
UltraDark.evolve_to!
UltraDark.good_phase_diff
UltraDark.inner_step!
UltraDark.k_norm
UltraDark.k_vec
UltraDark.mass
UltraDark.max_normed_phase_diff
UltraDark.max_time_step
UltraDark.max_time_step_external
UltraDark.max_time_step_grids
UltraDark.outer_step!
UltraDark.phase_diff
UltraDark.phase_diff
UltraDark.polar_angle
UltraDark.radius_cylindrical
UltraDark.radius_spherical
UltraDark.rk_norm
UltraDark.rk_vec
UltraDark.simulate!
UltraDark.take_steps!
UltraDark.update_gravitational_potential!
Docstrings
UltraDark.AbstractGrids
— TypeAbstractGrids
abstract type AbstractGrids
Abstract type for grids containing simulation data
UltraDark.Grids
— Typestruct Grids <: UltraDark.AbstractGrids
Grids(length, resol::Int)
+API · UltraDark.jl API
Index
UltraDark.Config
UltraDark.Output
UltraDark.Summary
UltraDark.AbstractGrids
UltraDark.Config.SimulationConfig
UltraDark.Config.TimeStepOptions
UltraDark.Config.TimeStepOptions
UltraDark.Grids
UltraDark.Output.OutputConfig
UltraDark.Output.OutputConfig
UltraDark.PencilGrids
UltraDark.Summary.AngularMomentum
UltraDark.Summary.EnergyGravity
UltraDark.Summary.EnergyKineticQuantum
UltraDark.Summary.MaxDensity
UltraDark.Summary.MaxDensityIndex
UltraDark.Summary.MeanDensity
UltraDark.Summary.RmsDensityContrast
UltraDark.Summary.ScaleFactor
UltraDark.Summary.SimulationTime
UltraDark.Summary.TimeStep
UltraDark.Summary.TotalMass
UltraDark.Summary.WallTime
UltraDark.Config.constant_scale_factor
UltraDark.E_grav
UltraDark.E_gravity_density
UltraDark.E_kq
UltraDark.E_total
UltraDark.Initialise.add_fdm_soliton!
UltraDark.Output.output_external_state
UltraDark.Output.output_external_state_header
UltraDark.Output.output_external_states_headers
UltraDark.Output.output_grids
UltraDark.Output.output_output_times
UltraDark.Output.output_state
UltraDark.Output.output_xyz
UltraDark.Summary.column_title
UltraDark.Summary.column_titles
UltraDark.Summary.generate_summary_row
UltraDark.Summary.get_relevant_data
UltraDark.Summary.map_summary_statistics
UltraDark.Summary.output_summary_header
UltraDark.Summary.output_summary_row
UltraDark.Summary.pool_summarystat
UltraDark.Summary.pool_summarystat
UltraDark.Summary.pool_summarystat
UltraDark.Summary.pool_summarystat
UltraDark.Summary.pool_summarystat
UltraDark.Summary.pool_summarystat
UltraDark.Summary.pool_summarystat
UltraDark.Summary.pool_summarystat
UltraDark.actual_time_step
UltraDark.add_external_potential!
UltraDark.angular_momentum
UltraDark.angular_momentum_density
UltraDark.auxiliary_step!
UltraDark.azimuthal_angle
UltraDark.dV
UltraDark.evolve_to!
UltraDark.good_phase_diff
UltraDark.inner_step!
UltraDark.k_norm
UltraDark.k_vec
UltraDark.mass
UltraDark.max_normed_phase_diff
UltraDark.max_time_step
UltraDark.max_time_step_external
UltraDark.max_time_step_grids
UltraDark.outer_step!
UltraDark.phase_diff
UltraDark.phase_diff
UltraDark.polar_angle
UltraDark.radius_cylindrical
UltraDark.radius_spherical
UltraDark.rk_norm
UltraDark.rk_vec
UltraDark.simulate!
UltraDark.take_steps!
UltraDark.update_gravitational_potential!
Docstrings
UltraDark.AbstractGrids
— TypeAbstractGrids
abstract type AbstractGrids
Abstract type for grids containing simulation data
sourceUltraDark.Grids
— Typestruct Grids <: UltraDark.AbstractGrids
Grids(length, resol::Int)
Grids(length_tuple, resol_tuple::Tuple{Int, Int, Int})
struct containing grids used in a simulation
Fields
x::Array{Float64, 3}
: Array of x positions
y::Array{Float64, 3}
: Array of y positions
z::Array{Float64, 3}
: Array of z positions
kx::Array{Float64, 3}
: Array of x Fourier modes
ky::Array{Float64, 3}
: Array of y Fourier modes
kz::Array{Float64, 3}
: Array of z Fourier modes
k::Array{Float64, 3}
: Fourier space postition array
rkx::Array{Float64, 3}
: Array of x Fourier modes for use with rfft
rky::Array{Float64, 3}
: Array of y Fourier modes for use with rfft
rkz::Array{Float64, 3}
: Array of z Fourier modes for use with rfft
rk::Array{Float64, 3}
: Fourier space postition array for use with rfft
ψx::Array{ComplexF64, 3}
: ψ field
ψk::Array{ComplexF64, 3}
: ψ field in Fourier space
ρx::Array{Float64, 3}
: density field ρ
ρk::Array{ComplexF64, 3}
: density field ρ in Fourier space
Φx::Array{Float64, 3}
: gravitational potential field Φ
Φk::Array{ComplexF64, 3}
: gravitational potential field Φ in fourier space
fft_plan::Any
: FFT plan for complex-to-complex transforms
rfft_plan::Any
: FFT plan for real-to-complex transforms
k_vanish_indices::Vector{CartesianIndex{3}}
: Indices at which k==0.0
rk_vanish_indices::Any
: Indices at which rk==0.0
Examples
Create an empty grid with length length
and resolution resol
julia> using UltraDark
julia> length = 1;
@@ -14,7 +14,7 @@
julia> Grids((1.0, 1.0, 0.5), (64, 64, 32));
julia> size(ans.ψx)
-(64, 64, 32)
sourceUltraDark.PencilGrids
— TypePencilGrids(length, resol)
+(64, 64, 32)
sourceUltraDark.PencilGrids
— TypePencilGrids(length, resol)
PencilGrids(length_tuple, resol_tuple::Tuple{Int, Int, Int})
struct containing grids used in a simulation
Each grid is a PencilArray
, allowing multiprocess FFTs. This comes with significant overhead so is only useful when running in a multi-node environment.
Fields
x::Array{Float64, 3}
: Array of x positions
y::Array{Float64, 3}
: Array of y positions
z::Array{Float64, 3}
: Array of z positions
kx::Array{Float64, 3}
: Array of x Fourier modes
ky::Array{Float64, 3}
: Array of y Fourier modes
kz::Array{Float64, 3}
: Array of z Fourier modes
k::Any
: Fourier space postition array
rkx::Array{Float64, 3}
: Array of x Fourier modes for use with rfft
rky::Array{Float64, 3}
: Array of y Fourier modes for use with rfft
rkz::Array{Float64, 3}
: Array of z Fourier modes for use with rfft
rk::Any
: Fourier space postition array for use with rfft
ψx::Any
: ψ field
ψk::Any
: ψ field in Fourier space
ρx::Any
: density field ρ
ρk::Any
: density field ρ in Fourier space
Φx::Any
: gravitational potential field Φ
Φk::Any
: gravitational potential field Φ in fourier space
fft_plan::Any
: FFT plan for complex-to-complex transforms
rfft_plan::Any
: FFT plan for real-to-complex transforms
k_vanish_indices::Vector{CartesianIndex{3}}
: Indices at which k==0.0
rk_vanish_indices::Any
: Indices at which rk==0.0
MPI_COMM::Any
: MPI communicator
Examples
Create an empty grid with length length
and resolution resol
. Uses PencilFFTs
to create PencilArrays
.
julia> using UltraDark
julia> len = 1;
@@ -25,19 +25,19 @@
Create an empty length[1]
xlength[2]
xlength[3]
grid with resolution resol[1]
xresol[2]
xresol[3]
.
julia> using UltraDark
julia> PencilGrids((1.0, 1.0, 0.5), (64, 64, 32));
-
sourceUltraDark.E_grav
— MethodE_grav(grids)
-E_grav(grids, psi)
Gravitational potential energy
sourceUltraDark.E_gravity_density
— MethodE_gravity_density(psi::Number, Phi::Real) -> Real
-
Gravitational energy density of field psi
in gravitational potential Phi
sourceUltraDark.E_kq
— MethodE_kq(grids)
-E_kq(grids, psi)
Sum of kinetic and quantum energies
sourceUltraDark.E_total
— MethodE_total(grids; constants)
-
Total energy of the scalar field: the sum of the kinetic and quantum energies.
sourceUltraDark.actual_time_step
— Methodactual_time_step(max_time_step, time_interval, time_step_options)
Actual size and number of time steps that should be taken if the maximum is max_time_step
. No more than time_step_options.update_period
steps should be taken, and they should fit in time_interval
.
Examples
julia> using UltraDark: actual_time_step, TimeStepOptions
+
sourceUltraDark.E_grav
— MethodE_grav(grids)
+E_grav(grids, psi)
Gravitational potential energy
sourceUltraDark.E_gravity_density
— MethodE_gravity_density(psi::Number, Phi::Real) -> Real
+
Gravitational energy density of field psi
in gravitational potential Phi
sourceUltraDark.E_kq
— MethodE_kq(grids)
+E_kq(grids, psi)
Sum of kinetic and quantum energies
sourceUltraDark.E_total
— MethodE_total(grids; constants)
+
Total energy of the scalar field: the sum of the kinetic and quantum energies.
sourceUltraDark.actual_time_step
— Methodactual_time_step(max_time_step, time_interval, time_step_options)
Actual size and number of time steps that should be taken if the maximum is max_time_step
. No more than time_step_options.update_period
steps should be taken, and they should fit in time_interval
.
Examples
julia> using UltraDark: actual_time_step, TimeStepOptions
julia> actual_time_step(0.11, 1, TimeStepOptions())
-(0.1, 10)
sourceUltraDark.add_external_potential!
— Methodadd_external_potential!(t, grids, constants)
Add a gravitational potential to the grid. By default this does nothing, but can be overridden in multiple dispatch.
sourceUltraDark.angular_momentum
— Methodangular_momentum(grids)
-angular_momentum(grids, ψx, ρx)
Calculate total angular momentum
Returns
L: AbstractArray with length 3
sourceUltraDark.angular_momentum_density
— Methodangular_momentum_density(grids)
-angular_momentum_density(grids, ψx, ρx)
Calculate angular momentum density at each grid point
Returns
L: AbstractArray with dimensions 3 x resolx x resoly x resol_z
sourceUltraDark.auxiliary_step!
— Methodauxiliary_step!(Δt, grids, t, constants)
-auxiliary_step!(Δt, grids, t, constants, s; a = 1.0)
Do an auxiliary inner step. By default this does nothing, but can be overridden in multiple dispatch.
sourceUltraDark.azimuthal_angle
— Methodazimuthal_angle(x, y, z)
+(0.1, 10)
sourceUltraDark.add_external_potential!
— Methodadd_external_potential!(t, grids, constants)
Add a gravitational potential to the grid. By default this does nothing, but can be overridden in multiple dispatch.
sourceUltraDark.angular_momentum
— Methodangular_momentum(grids)
+angular_momentum(grids, ψx, ρx)
Calculate total angular momentum
Returns
L: AbstractArray with length 3
sourceUltraDark.angular_momentum_density
— Methodangular_momentum_density(grids)
+angular_momentum_density(grids, ψx, ρx)
Calculate angular momentum density at each grid point
Returns
L: AbstractArray with dimensions 3 x resolx x resoly x resol_z
sourceUltraDark.auxiliary_step!
— Methodauxiliary_step!(Δt, grids, t, constants)
+auxiliary_step!(Δt, grids, t, constants, s; a = 1.0)
Do an auxiliary inner step. By default this does nothing, but can be overridden in multiple dispatch.
sourceUltraDark.azimuthal_angle
— Methodazimuthal_angle(x, y, z)
azimuthal_angle(grids)
-azimuthal_angle(grids, r0)
Calculate the azimuthal angle in spherical or cylindrical coordinates
This is \phi in conventional physics notation.
sourceUltraDark.dV
— MethoddV(grids) -> Any
+azimuthal_angle(grids, r0)
Calculate the azimuthal angle in spherical or cylindrical coordinates
This is \phi in conventional physics notation.
sourceUltraDark.dV
— MethoddV(grids) -> Any
Calculate the volume of each grid cell
Examples
julia> using UltraDark
julia> box_length = 1.0;
@@ -47,7 +47,7 @@
julia> g = Grids(box_length, resol);
julia> dV(g) * resol^3 == box_length^3
-true
sourceUltraDark.evolve_to!
— Methodevolve_to!(
+true
sourceUltraDark.evolve_to!
— Methodevolve_to!(
t_start,
t_end,
grids,
@@ -56,9 +56,9 @@
constants,
external_states
) -> Any
-
Evolve grids
forward from t_start
to t_end
sourceUltraDark.good_phase_diff
— Methodbad_phase_diff(grids, config)
Check if the phase of the ψ field is in a trustable regime.
Returns
sourceUltraDark.inner_step!
— Methodinner_step!(Δt, grids, constants; a=1.0)
-inner_step!(Δt, grids, constants, s; a=1.0)
Perform the "inner" time step in the symmetrized split-step Fourier method.
This step applies the diffusion terms and updates the gravitational potential.
sourceUltraDark.k_norm
— Methodk_norm(lengths, resols) -> Any
-
sourceUltraDark.k_vec
— Methodk_vec(
+
Evolve grids
forward from t_start
to t_end
sourceUltraDark.good_phase_diff
— Methodbad_phase_diff(grids, config)
Check if the phase of the ψ field is in a trustable regime.
Returns
sourceUltraDark.inner_step!
— Methodinner_step!(Δt, grids, constants; a=1.0)
+inner_step!(Δt, grids, constants, s; a=1.0)
Perform the "inner" time step in the symmetrized split-step Fourier method.
This step applies the diffusion terms and updates the gravitational potential.
sourceUltraDark.k_norm
— Methodk_norm(lengths, resols) -> Any
+
sourceUltraDark.k_vec
— Methodk_vec(
lengths,
resols
) -> Tuple{AbstractFFTs.Frequencies, AbstractFFTs.Frequencies, AbstractFFTs.Frequencies}
@@ -71,7 +71,7 @@
0.0
1.0
-2.0
- -1.0
sourceUltraDark.mass
— Methodmass(grids)
+ -1.0
sourceUltraDark.mass
— Methodmass(grids)
mass(grids, rho)
Calculate total mass of a density field
Examples
julia> using UltraDark
julia> g = Grids(1.0, 16);
@@ -81,11 +81,11 @@
julia> g.ρx[1, 1, 1] = 1.0;
julia> UltraDark.mass(g) == 1.0 * (1.0 / 16)^3
-true
sourceUltraDark.max_normed_phase_diff
— Methodnormed_max_phase_grad(grids)
Compute maximum phase gradient of a grid
Normalised to ignore large gradients in regions with low density. These tend to be anomalous.
sourceUltraDark.max_time_step
— Methodmax_time_step(grids, a, external_states)
Consolidate the maximum time step implied by grids
and each member of external_states
.
sourceUltraDark.max_time_step_external
— Methodmax_time_step_external(grids, a, state)
Calculate the maximum time step implied by an external state
sourceUltraDark.max_time_step_grids
— Methodmax_time_step_grids(grids, a)
-max_time_step_grids(grids::PencilGrids, a)
Calculate an upper bound on the time step from grid properties
This time step depends on the gravitational potential and the resolution.
sourceUltraDark.outer_step!
— Methodouter_step!(Δt, grids, constants; a=1.0)
-outer_step!(Δt, grids, constants, s; a=1.0)
Perform the "outer" time step in the symmetrized split-step Fourier method.
This step only updates the phase of ψ applying accelerations due to gravity, the amplitude is not changed.
sourceUltraDark.phase_diff
— Methodphase_diff(field, dir)
Compute point-to-point difference of phase on a grid along a direction
Returns an array of size (size(field)[1], size(field)[2], size(field)[3])
containing differences in direction dir
.
sourceUltraDark.phase_diff
— Methodphase_diff(field::PencilArray, dir)
Compute point-to-point difference of phase on a grid along a direction
Returns an array of size (size(field)[1], size(field)[2], size(field)[3])
containing differences in direction dir
.
sourceUltraDark.polar_angle
— Methodpolar_angle(x, y, z)
+true
sourceUltraDark.max_normed_phase_diff
— Methodnormed_max_phase_grad(grids)
Compute maximum phase gradient of a grid
Normalised to ignore large gradients in regions with low density. These tend to be anomalous.
sourceUltraDark.max_time_step
— Methodmax_time_step(grids, a, external_states)
Consolidate the maximum time step implied by grids
and each member of external_states
.
sourceUltraDark.max_time_step_external
— Methodmax_time_step_external(grids, a, state)
Calculate the maximum time step implied by an external state
sourceUltraDark.max_time_step_grids
— Methodmax_time_step_grids(grids, a)
+max_time_step_grids(grids::PencilGrids, a)
Calculate an upper bound on the time step from grid properties
This time step depends on the gravitational potential and the resolution.
sourceUltraDark.outer_step!
— Methodouter_step!(Δt, grids, constants; a=1.0)
+outer_step!(Δt, grids, constants, s; a=1.0)
Perform the "outer" time step in the symmetrized split-step Fourier method.
This step only updates the phase of ψ applying accelerations due to gravity, the amplitude is not changed.
sourceUltraDark.phase_diff
— Methodphase_diff(field, dir)
Compute point-to-point difference of phase on a grid along a direction
Returns an array of size (size(field)[1], size(field)[2], size(field)[3])
containing differences in direction dir
.
sourceUltraDark.phase_diff
— Methodphase_diff(field::PencilArray, dir)
Compute point-to-point difference of phase on a grid along a direction
Returns an array of size (size(field)[1], size(field)[2], size(field)[3])
containing differences in direction dir
.
sourceUltraDark.polar_angle
— Methodpolar_angle(x, y, z)
polar_angle(grids)
-polar_angle(grids, r0)
Calculate the polar angle in spherical coordinates
This is \theta in conventional physics notation.
sourceUltraDark.radius_cylindrical
— Methodradius_cylindrical(x, y, z)
+polar_angle(grids, r0)
Calculate the polar angle in spherical coordinates
This is \theta in conventional physics notation.
sourceUltraDark.radius_cylindrical
— Methodradius_cylindrical(x, y, z)
radius_cylindrical(grids)
radius_cylindrical(grids, r0)
Calculate the radial coordinate in cylindrical coordinates
Examples
julia> using UltraDark
@@ -104,7 +104,7 @@
radius_cylindrical(g, (0.0, 0.0, 1.0)) .* cos.(azimuthal_angle(g, (0.0, 0.0, 1.0))) .≈
g.x,
)
-true
sourceUltraDark.radius_spherical
— Methodradius_spherical(x, y, z)
+true
sourceUltraDark.radius_spherical
— Methodradius_spherical(x, y, z)
radius_spherical(grids)
radius_spherical(grids, r0)
Calculate the radial coordinate in a spherical coordinate system
Examples
julia> using UltraDark
@@ -123,13 +123,13 @@
radius_spherical(g, (1.0, 0.0, 0.0)) .* sin.(polar_angle(g, (1.0, 0.0, 0.0))) .*
cos.(azimuthal_angle(g, (1.0, 0.0, 0.0))) .+ 1.0 .≈ g.x,
)
-true
sourceUltraDark.rk_norm
— Methodrk_norm(lengths, resols) -> Any
-
sourceUltraDark.rk_vec
— Methodrk_vec(
+true
sourceUltraDark.rk_norm
— Methodrk_norm(lengths, resols) -> Any
+
sourceUltraDark.rk_vec
— Methodrk_vec(
lengths,
resols
) -> Tuple{AbstractFFTs.Frequencies, AbstractFFTs.Frequencies, AbstractFFTs.Frequencies}
-
sourceUltraDark.simulate!
— Methodsimulate!(grids, output_config::OutputConfig; constants = nothing, external_states = (),)
-simulate!(grids, sim_config, output_config::OutputConfig; constants = nothing, external_states = (),)
simulate!
is the main entry point into a simulation
simulate!
evolves grids
and external_states
forward, writing output as specified by output_config
.
Arguments
grids::AbstractGrids
Contains coordinate systems and the scalar field ψ
.
sim_config::UltraDark.Config
gives further control over the way the simulation is done.
output_config::OutputConfig
controls what output is written and when.
constants::Any
can be used to overload other functions in the evolution, for example to introduce self-interactions.
external_states::Tuple{Any}
can be used in combination with overloading to add other dynamical objects to a simulation.
sourceUltraDark.take_steps!
— MethodTake n
steps with time step Δt
Examples
julia> using UltraDark: take_steps!, Grids, OutputConfig, Config
+
sourceUltraDark.simulate!
— Methodsimulate!(grids, output_config::OutputConfig; constants = nothing, external_states = (),)
+simulate!(grids, sim_config, output_config::OutputConfig; constants = nothing, external_states = (),)
simulate!
is the main entry point into a simulation
simulate!
evolves grids
and external_states
forward, writing output as specified by output_config
.
Arguments
grids::AbstractGrids
Contains coordinate systems and the scalar field ψ
.
sim_config::UltraDark.Config
gives further control over the way the simulation is done.
output_config::OutputConfig
controls what output is written and when.
constants::Any
can be used to overload other functions in the evolution, for example to introduce self-interactions.
external_states::Tuple{Any}
can be used in combination with overloading to add other dynamical objects to a simulation.
sourceUltraDark.take_steps!
— MethodTake n
steps with time step Δt
Examples
julia> using UltraDark: take_steps!, Grids, OutputConfig, Config
julia> take_steps!(
Grids(1.0, 16),
@@ -141,5 +141,5 @@
nothing,
(),
)
-5.0
sourceUltraDark.update_gravitational_potential!
— Methodupdate_gravitational_potential!(grids; a = 1.0)
-update_gravitational_potential!(grids, constants; a = 1.0)
Update density grids.ρx
and the gravitational potential grids.Φx
based on grids.ψx
sourceSettings
This document was generated with Documenter.jl version 1.3.0 on Tuesday 14 May 2024. Using Julia version 1.10.3.
+5.0
UltraDark.update_gravitational_potential!
— Methodupdate_gravitational_potential!(grids; a = 1.0)
+update_gravitational_potential!(grids, constants; a = 1.0)
Update density grids.ρx
and the gravitational potential grids.Φx
based on grids.ψx