From dc00d23f51996e718bf90559d0d535b3c9cdda7f Mon Sep 17 00:00:00 2001 From: Stefan Kroboth Date: Sat, 17 Feb 2024 18:06:49 +0100 Subject: [PATCH] Created READMEs for observers and checkpointing, updated docs --- crates/argmin-checkpointing-file/README.md | 64 ++++++++++++ crates/argmin-checkpointing-file/src/lib.rs | 33 +++++++ crates/argmin-observer-paramwriter/Cargo.toml | 2 +- crates/argmin-observer-paramwriter/README.md | 65 ++++++++++++ crates/argmin-observer-paramwriter/src/lib.rs | 29 +++++- crates/argmin-observer-slog/README.md | 63 ++++++++++++ crates/argmin-observer-slog/src/lib.rs | 29 +++++- crates/argmin-observer-spectator/README.md | 65 ++++++++++++ crates/argmin-observer-spectator/src/lib.rs | 2 - crates/spectator/README.md | 98 +++++++++++++++++++ crates/spectator/src/lib.rs | 38 ++++++- 11 files changed, 478 insertions(+), 10 deletions(-) create mode 100644 crates/argmin-checkpointing-file/README.md create mode 100644 crates/argmin-observer-paramwriter/README.md create mode 100644 crates/argmin-observer-slog/README.md create mode 100644 crates/argmin-observer-spectator/README.md create mode 100644 crates/spectator/README.md diff --git a/crates/argmin-checkpointing-file/README.md b/crates/argmin-checkpointing-file/README.md new file mode 100644 index 000000000..89ea8450d --- /dev/null +++ b/crates/argmin-checkpointing-file/README.md @@ -0,0 +1,64 @@ +

+ +

+

argmin-checkpointing-file

+ +

+ Website + | + Book + | + Docs (latest release) + | + Docs (main branch) +

+ +

+ Crates.io version + Crates.io downloads + GitHub Actions workflow status + License + argmin Discord +

+ +Saves a checkpoint on disk from which an interrupted optimization run can be resumed. +For details on the usage please see the documentation ([latest release](https://docs.rs/argmin-checkpointing-file) +or [current main](https://argmin-rs.github.io/argmin/argmin_checkpointing_file/index.html)) +or the [argmin book](https://argmin-rs.org/book/) or have a look at +the [example](https://github.com/argmin-rs/argmin/tree/main/examples/checkpoint). + +## License + +Licensed under either of + + * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0) + * MIT License ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT) + +at your option. + +### Contribution + +Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, +as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions. diff --git a/crates/argmin-checkpointing-file/src/lib.rs b/crates/argmin-checkpointing-file/src/lib.rs index 7001c14c1..303759e6a 100644 --- a/crates/argmin-checkpointing-file/src/lib.rs +++ b/crates/argmin-checkpointing-file/src/lib.rs @@ -5,6 +5,39 @@ // http://opensource.org/licenses/MIT>, at your option. This file may not be // copied, modified, or distributed except according to those terms. +//! This crate creates checkpoints on disk for an optimization run. +//! +//! Saves a checkpoint on disk from which an interrupted optimization run can be resumed. +//! For details on the usage please see the documentation of [`FileCheckpoint`] or have a look at +//! the [example](https://github.com/argmin-rs/argmin/tree/main/examples/checkpoint). +//! +//! # Usage +//! +//! Add the following line to your dependencies list: +//! +//! ```toml +//! [dependencies] +#![doc = concat!("argmin-checkpointing-file = \"", env!("CARGO_PKG_VERSION"), "\"")] +//! ``` +//! +//! # License +//! +//! Licensed under either of +//! +//! * Apache License, Version 2.0, +//! ([LICENSE-APACHE](https://github.com/argmin-rs/argmin/blob/main/LICENSE-APACHE) or +//! ) +//! * MIT License ([LICENSE-MIT](https://github.com/argmin-rs/argmin/blob/main/LICENSE-MIT) or +//! ) +//! +//! at your option. +//! +//! ## Contribution +//! +//! Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion +//! in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, +//! without any additional terms or conditions. + pub use argmin::core::checkpointing::{Checkpoint, CheckpointingFrequency}; use argmin::core::Error; use serde::{de::DeserializeOwned, Serialize}; diff --git a/crates/argmin-observer-paramwriter/Cargo.toml b/crates/argmin-observer-paramwriter/Cargo.toml index b705cbf77..0628f6258 100644 --- a/crates/argmin-observer-paramwriter/Cargo.toml +++ b/crates/argmin-observer-paramwriter/Cargo.toml @@ -15,7 +15,7 @@ exclude = [] [dependencies] argmin = { version = "0.9.0", path = "../argmin", default-features = false } -bincode = { version = "1.3.3" } +bincode = { version = "1.3" } serde = { version = "1.0", features = ["derive", "rc"] } serde_json = { version = "1.0" } diff --git a/crates/argmin-observer-paramwriter/README.md b/crates/argmin-observer-paramwriter/README.md new file mode 100644 index 000000000..a1a323815 --- /dev/null +++ b/crates/argmin-observer-paramwriter/README.md @@ -0,0 +1,65 @@ +

+ +

+

argmin-observer-paramwriter

+ +

+ Website + | + Book + | + Docs (latest release) + | + Docs (main branch) +

+ +

+ Crates.io version + Crates.io downloads + GitHub Actions workflow status + License + argmin Discord +

+ +This argmin observer writes serialized parameter vectors to files during optimization. +Details can be found in the documentation ([latest release](https://docs.rs/argmin-observer-paramwriter) or +[current main](https://argmin-rs.github.io/argmin/argmin_observer_paramwriter/index.html)) +or the [argmin book](https://argmin-rs.org/book/). +There is also an [example](https://github.com/argmin-rs/argmin/tree/main/examples/paramwriter) +which illustrates how to use the observer. + +## License + +Licensed under either of + + * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0) + * MIT License ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT) + +at your option. + +### Contribution + +Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, +as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions. diff --git a/crates/argmin-observer-paramwriter/src/lib.rs b/crates/argmin-observer-paramwriter/src/lib.rs index c896a1967..f91ce036b 100644 --- a/crates/argmin-observer-paramwriter/src/lib.rs +++ b/crates/argmin-observer-paramwriter/src/lib.rs @@ -5,9 +5,36 @@ // http://opensource.org/licenses/MIT>, at your option. This file may not be // copied, modified, or distributed except according to those terms. -//! # Write parameter vectors to a file during optimization. +//! Writes parameter vectors to a file during optimization. //! //! See documentation of [`ParamWriter`] and [`ParamWriterFormat`] for details. +//! +//! # Usage +//! +//! Add the following line to your dependencies list: +//! +//! ```toml +//! [dependencies] +#![doc = concat!("argmin-observer-paramwriter = \"", env!("CARGO_PKG_VERSION"), "\"")] +//! ``` +//! +//! # License +//! +//! Licensed under either of +//! +//! * Apache License, Version 2.0, +//! ([LICENSE-APACHE](https://github.com/argmin-rs/argmin/blob/main/LICENSE-APACHE) or +//! ) +//! * MIT License ([LICENSE-MIT](https://github.com/argmin-rs/argmin/blob/main/LICENSE-MIT) or +//! ) +//! +//! at your option. +//! +//! ## Contribution +//! +//! Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion +//! in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, +//! without any additional terms or conditions. use argmin::core::observers::Observe; use argmin::core::{Error, State, KV}; diff --git a/crates/argmin-observer-slog/README.md b/crates/argmin-observer-slog/README.md new file mode 100644 index 000000000..b02e55b88 --- /dev/null +++ b/crates/argmin-observer-slog/README.md @@ -0,0 +1,63 @@ +

+ +

+

argmin-observer-slog

+ +

+ Website + | + Book + | + Docs (latest release) + | + Docs (main branch) +

+ +

+ Crates.io version + Crates.io downloads + GitHub Actions workflow status + License + argmin Discord +

+ +This argmin observer logs the progress of the optimization to the terminal or to disk. +Details can be found in the documentation ([latest release](https://docs.rs/argmin-observer-slog) or +[current main](https://argmin-rs.github.io/argmin/argmin_observer_slog/index.html)) +or the [argmin book](https://argmin-rs.org/book/). + +## License + +Licensed under either of + + * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0) + * MIT License ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT) + +at your option. + +### Contribution + +Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, +as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions. diff --git a/crates/argmin-observer-slog/src/lib.rs b/crates/argmin-observer-slog/src/lib.rs index b481134ad..a05fba08c 100644 --- a/crates/argmin-observer-slog/src/lib.rs +++ b/crates/argmin-observer-slog/src/lib.rs @@ -5,12 +5,39 @@ // http://opensource.org/licenses/MIT>, at your option. This file may not be // copied, modified, or distributed except according to those terms. -//! # Loggers based on the `slog` crate +//! This crate contains loggers based on the `slog` crate. //! //! These loggers write general information about the optimization and information about the //! progress of the optimization for each iteration of the algorithm to screen or into a file in //! JSON format. //! See [`SlogLogger`] for details regarding usage. +//! +//! # Usage +//! +//! Add the following line to your dependencies list: +//! +//! ```toml +//! [dependencies] +#![doc = concat!("argmin-observer-slog = \"", env!("CARGO_PKG_VERSION"), "\"")] +//! ``` +//! +//! # License +//! +//! Licensed under either of +//! +//! * Apache License, Version 2.0, +//! ([LICENSE-APACHE](https://github.com/argmin-rs/argmin/blob/main/LICENSE-APACHE) or +//! ) +//! * MIT License ([LICENSE-MIT](https://github.com/argmin-rs/argmin/blob/main/LICENSE-MIT) or +//! ) +//! +//! at your option. +//! +//! ## Contribution +//! +//! Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion +//! in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, +//! without any additional terms or conditions. use argmin::core::observers::Observe; use argmin::core::{Error, State, KV}; diff --git a/crates/argmin-observer-spectator/README.md b/crates/argmin-observer-spectator/README.md new file mode 100644 index 000000000..a8a3aad60 --- /dev/null +++ b/crates/argmin-observer-spectator/README.md @@ -0,0 +1,65 @@ +

+ +

+

argmin-observer-spectator

+ +

+ Website + | + Book + | + Docs (latest release) + | + Docs (main branch) +

+ +

+ Crates.io version + Crates.io downloads + GitHub Actions workflow status + License + argmin Discord +

+ +This observer sends metrics and parameter vectors to a Spectator instance. +For details on the usage please see the documentation ([latest release](https://docs.rs/argmin-observer-spectator) +or [current main](https://argmin-rs.github.io/argmin/argmin_observer_spectator/index.html)) +or the [argmin book](https://argmin-rs.org/book/) or have a look at +the [example 1](https://github.com/argmin-rs/argmin/tree/main/examples/spectator_basic) +and the [example 2](https://github.com/argmin-rs/argmin/tree/main/examples/spectator_multiple). + +## License + +Licensed under either of + + * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0) + * MIT License ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT) + +at your option. + +### Contribution + +Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, +as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions. diff --git a/crates/argmin-observer-spectator/src/lib.rs b/crates/argmin-observer-spectator/src/lib.rs index f73352aff..7233e36b4 100644 --- a/crates/argmin-observer-spectator/src/lib.rs +++ b/crates/argmin-observer-spectator/src/lib.rs @@ -5,8 +5,6 @@ // http://opensource.org/licenses/MIT>, at your option. This file may not be // copied, modified, or distributed except according to those terms. -//! # Observer for Spectator -//! //! This observer sends metrics and parameter vectors to a Spectator instance. //! //! ## Example diff --git a/crates/spectator/README.md b/crates/spectator/README.md new file mode 100644 index 000000000..4f66129e4 --- /dev/null +++ b/crates/spectator/README.md @@ -0,0 +1,98 @@ +

+ +

+

Spectator

+ +

+ Website + | + Book + | + Docs (latest release) + | + Docs (main branch) +

+ +

+ Crates.io version + Crates.io downloads + GitHub Actions workflow status + License + argmin Discord +

+ +Spectator is a GUI tool to observe the progress of argmin optimization runs. + +## Installation + +The preferred way is to install directly from crates.io: + +```bash +cargo install spectator --locked +``` + +Alternatively, one can clone the repo and install/run from there: + +```bash +git clone https://github.com/argmin-rs/argmin.git +cd argmin + +# Compile and run from the repo... +cargo build -p spectator --release +./target/release/spectator + +# .. or directly run from the repo... +cargo run -p spectator --release + +# ... or install locally +cargo install -p spectator +spectator +``` + +## Usage + +```bash +spectator --host 127.0.0.1 --port 5498 +``` + +The optional options `--host` and `--port` indicate the host and port spectator binds to. +By default, spectator will bind to `0.0.0.0:5498`. + +The argmin optimization run which should be observed needs to use the spectator observer which +can be found [in the `argmin-observer-spectator` crate](https://crates.io/crates/argmin-observer-spectator). + +## License + +Licensed under either of + + * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0) + * MIT License ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT) + +at your option. + +### Contribution + +Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, +as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions. diff --git a/crates/spectator/src/lib.rs b/crates/spectator/src/lib.rs index b821d2f74..c4768c418 100644 --- a/crates/spectator/src/lib.rs +++ b/crates/spectator/src/lib.rs @@ -5,17 +5,45 @@ // http://opensource.org/licenses/MIT>, at your option. This file may not be // copied, modified, or distributed except according to those terms. -//! # spectator -//! -//! Spectator is a dedicated GUI program which displays the progress of an optimization run. -//! The data is fed to spectator by the `argmin-observer-spectator`. +//! Spectator is a GUI tool to observe the progress of an optimization run. +//! The data is transferred to spectator by the argmin observer +//! [`argmin-observer-spectator`](https://crates.io/crates/argmin-observer-spectator). //! //! ## Installation //! +//! The preferred way is to install directly from crates.io: +//! +//! ```bash +//! cargo install spectator --locked +//! ``` +//! +//! Alternatively, one can clone the repo and install/run from there: +//! +//! ```bash +//! git clone https://github.com/argmin-rs/argmin.git +//! cd argmin +//! +//! # Compile and run from the repo... +//! cargo build -p spectator --release +//! ./target/release/spectator +//! +//! # .. or directly run from the repo... +//! cargo run -p spectator --release +//! +//! # ... or install locally +//! cargo install -p spectator +//! spectator +//! ``` +//! +//! ## Usage +//! //! ```bash -//! cargo install spectator +//! spectator --host 127.0.0.1 --port 5498 //! ``` //! +//! The optional options `--host` and `--port` indicate the host and port spectator binds to. +//! By default, spectator will bind to `0.0.0.0:5498`. +//! //! ## Library //! //! This crate can also be used as a library and exposes the [`Message`] type used to encode data