Skip to content

Commit

Permalink
[doc], [compat] release 0.1.1
Browse files Browse the repository at this point in the history
  • Loading branch information
islent committed Nov 26, 2021
1 parent 901d337 commit e91ffbc
Show file tree
Hide file tree
Showing 19 changed files with 360 additions and 32 deletions.
2 changes: 1 addition & 1 deletion .github/workflows/CI.yml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
name: CI

on: [push, pull_request]
on: [push, pull_request, workflow_dispatch]

# 64-bit Julia only
jobs:
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/CompatHelper.yml
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ jobs:
runs-on: ${{ matrix.os }}
strategy:
matrix:
julia-version: [1.5.0]
julia-version: [1.6.0]
julia-arch: [x64]
os: [ubuntu-latest]
steps:
Expand Down
4 changes: 2 additions & 2 deletions .github/workflows/CompatHelperManual.yml
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
name: CompatHelper

on:
[push, pull_request]
[push, pull_request, workflow_dispatch]

jobs:
CompatHelper:
runs-on: ${{ matrix.os }}
if: "contains(github.event.head_commit.message, '[compat]')"
strategy:
matrix:
julia-version: [1.5.0]
julia-version: [1.6.0]
julia-arch: [x64]
os: [ubuntu-latest]
steps:
Expand Down
25 changes: 25 additions & 0 deletions .github/workflows/ManuallyBuildDoc.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
name: ManuallyBuildDoc

on:
[push, pull_request, workflow_dispatch]

# 64-bit Julia only
jobs:
build:
runs-on: ubuntu-latest
if: "contains(github.event.head_commit.message, '[doc]')"
steps:
- uses: actions/checkout@v1
- uses: julia-actions/setup-julia@latest
with:
version: '1.6.0'
- run: julia --project=docs -e '
using Pkg;
Pkg.add("Documenter");
Pkg.develop(PackageSpec(; path=pwd()));
Pkg.instantiate();'
- name: Build and deploy doc
env:
#GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Deploying to else where, so use SSH instead
DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
run: julia --project=docs --color=yes docs/make.jl
15 changes: 15 additions & 0 deletions .github/workflows/TagBot.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
name: TagBot
on:
issue_comment:
types:
- created
workflow_dispatch:
jobs:
TagBot:
if: github.event_name == 'workflow_dispatch' || github.actor == 'JuliaTagBot'
runs-on: ubuntu-latest
steps:
- uses: JuliaRegistries/TagBot@v1
with:
token: ${{ secrets.GITHUB_TOKEN }}
ssh: ${{ secrets.DOCUMENTER_KEY }}
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -13,3 +13,5 @@ test/testGadgetArray.gadget2
test/ramses.csv
test/testFileIO.gadget2
test/pot_acc.format2.test.gadget2

docs/build
4 changes: 3 additions & 1 deletion Project.toml
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,9 @@ IterTools = "1.3"
JLD2 = "0.4"
PhysicalParticles = "1"
ProgressMeter = "1"
Reexport = "1"
StaticArrays = "1"
StructArrays = "0.6"
Unitful = "1"
UnitfulAstro = "1"
julia = "1.6.0"
julia = "1.6"
31 changes: 28 additions & 3 deletions Readme.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,17 +3,40 @@
I/O interface for astrophysical simulation codes

[![codecov](https://codecov.io/gh/JuliaAstroSim/AstroIO.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/JuliaAstroSim/AstroIO.jl)
[![][docs-dev-img]][docs-dev-url]

## Installation

```julia
]add AstroIO
```

or

```julia
using Pkg; Pkg.add("AstroIO")
```

or

```julia
]add https://github.com/JuliaAstroSim/AstroIO.jl
using Pkg; Pkg.add("https://github.com/JuliaAstroSim/AstroIO.jl")
```

To test the Package:
```julia
]test AstroIO
```

## Documentation

- [**Dev**][docs-dev-url] — *documentation of the in-development version.*

[docs-dev-img]: https://img.shields.io/badge/docs-dev-blue.svg
[docs-dev-url]: https://juliaastrosim.github.io/AstroIO.jl/dev

For beginners, it is highly recommended to read the [documentation of PhysicalParticles.jl](https://juliaastrosim.github.io/PhysicalParticles.jl/dev/).

## Usage

```julia
Expand All @@ -25,14 +48,16 @@ using AstroIO
Suffixes `gadget2`, `Gadget2`, `GADGET2` are supported

```julia
header, data = read_gadget2("snapshot.gadget2")
header, data = read_gadget2("snapshot.gadget2", uAstro)

write_gadget2("output.Gadget2", header, data)

# If only data provided, a default header would be generated
write_gadget2("output.GADGET2", data)
```

Supported units: `uAstro`, `uGadget2`, `uSI`, `uCSG`.

### Use FileIO interfaces

```julia
Expand All @@ -49,7 +74,7 @@ write_csv("output", csv) # No suffix
### Save and load with JLD2

```julia
write_gadget2_jld("output.jld2", header, data)
write_gadget2_jld("output.jld2", header, data, uGadget2)
write_jld("NoHeader.jld2", data)

header, data = read_gadget2_jld("output.jld2")
Expand Down
7 changes: 7 additions & 0 deletions docs/Project.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
[deps]
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
PhysicalParticles = "78724250-4eb2-11e9-0f34-13a7aab864c5"

[compat]
Documenter = "0.27"
PhysicalParticles = "1"
55 changes: 55 additions & 0 deletions docs/make.jl
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
"""
Compile with:
julia --project=docs/ --color=yes docs/make.jl
Generate key:
DocumenterTools.genkeys(user="JuliaAstroSim", repo="[email protected]:JuliaAstroSim/AstroIO.jl.git")
"""

using Documenter

using AstroIO

# The DOCSARGS environment variable can be used to pass additional arguments to make.jl.
# This is useful on CI, if you need to change the behavior of the build slightly but you
# can not change the .travis.yml or make.jl scripts any more (e.g. for a tag build).
if haskey(ENV, "DOCSARGS")
for arg in split(ENV["DOCSARGS"])
(arg in ARGS) || push!(ARGS, arg)
end
end

makedocs(
modules = [AstroIO],
format = Documenter.HTML(
# Use clean URLs, unless built as a "local" build
prettyurls = !("local" in ARGS),
canonical = "https://juliaastrosims.github.io/AstroIO.jl/dev/",
assets = ["assets/alpha_small.ico"],
analytics = "UA-153693590-1",
highlights = ["llvm", "yaml"],
),
clean = false,
sitename = "AstroIO.jl",
authors = "islent",
linkcheck = !("skiplinks" in ARGS),
pages = [
"Home" => "index.md",
"Manual" => Any[
"manual/guide.md",
"manual/gadget2.md",
"manual/tools.md",
],
"Library" => Any[
"lib/Methods.md",
],
#"contributing.md",
],
#strict = !("strict=false" in ARGS),
#doctest = ("doctest=only" in ARGS) ? :only : true,
)

deploydocs(
repo = "github.com/JuliaAstroSim/AstroIO.jl.git",
target = "build",
)
Binary file added docs/src/assets/alpha_small.ico
Binary file not shown.
44 changes: 44 additions & 0 deletions docs/src/assets/logo.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
17 changes: 17 additions & 0 deletions docs/src/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
# AstroIO.jl

*File I/O interfaces for astrophysical simulations*

## Package Feature

- FileIO.jl interfaces
- Supported formats:
- Gadget-2
- JLD2
- CSV
- HDF5 (work in progress)

## Manual Outline

```@contents
```
34 changes: 34 additions & 0 deletions docs/src/lib/Methods.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
# Methods

## Index

```@index
Pages = ["Methods.md"]
```

## Gadget2

```@docs
read_gadget2
read_gadget2_pos
write_gadget2
write_gadget2_format2
load(::Stream{format"Gadget2"})
save(::Stream{format"Gadget2"})
```

## JLD2

```@docs
read_jld
read_gadget2_jld
write_jld
write_gadget2_jld
```

## Tools

```@docs
renamesuffixs
renamereplace
```
49 changes: 49 additions & 0 deletions docs/src/manual/gadget2.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
# Gadget2 I/O

The default units in Gadget-2 snapshots are collected as `uGadget2`.
However, it is much more convenient to use `uAstro` in simulations:
```@repl gadget2
using PhysicalParticles, AstroIO
uGadget2
uAstro
```

### Basic usage

Units are automatedly converted during I/O:
```julia
# read default uGadget2 units from file and convert to uAstro
header, data = read_gadget2("snapshot.gadget2", uAstro);

# manually set the units in snapshot file
header, data = read_gadget2("snapshot.gadget2", uAstro, uGadget2);

# read default uGadget2 units from file and convert to unitless
header, data = read_gadget2("snapshot.gadget2", nothing, uGadget2);

# write in default uGadget2 units
write_gadget2("output.Gadget2", header, data)

# write in uAstro units
write_gadget2("output.Gadget2", header, data, uAstro)
# and read in uAstro units
header, data = read_gadget2("snapshot.gadget2", uAstro, uAstro);
```
Be careful with these unit conversions!

In some cases (for example, visualization), it is more efficient to only read position data from file:
```julia
read_gadget2_pos("snapshot.gadget2", uAstro)
read_gadget2_pos("snapshot.gadget2", uAstro, uGadget2)
```

### FileIO interfaces

FileIO provides `load` and `save` interfaces to I/O snapshots:
```julia
header, data = load("snapshot.gadget2")
save("FileIO.gadget2", header, data)

header, data = load("snapshot.gadget2", uAstro, uGadget2)
save("FileIO.gadget2", header, data, uGadget2)
```
Loading

0 comments on commit e91ffbc

Please sign in to comment.