Skip to content

Commit

Permalink
- added CLI manual to the Quick Start
Browse files Browse the repository at this point in the history
  • Loading branch information
@amkrajewski
amkrajewski committed Jan 29, 2024
1 parent 77e8679 commit 749bff7
Showing 1 changed file with 218 additions and 0 deletions.
218 changes: 218 additions & 0 deletions examples/quickstart.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@
"nimble install -y arraymancer nimpy\n",
"conda install -y python=3.11 jupyter numpy pandas plotly\n",
"pip install pqam-rmsadtandoc2023\n",
"nim c --d:release --out:examples/nimplex nimplex\n",
"nim c --d:release --threads:on --app:lib --out:examples/nimplex.so nimplex\n",
"nim c --d:release --threads:on --app:lib --out:examples/utils/plotting.so utils/plotting\n",
"```\n",
Expand Down Expand Up @@ -27579,6 +27580,223 @@
" template='plotly_white', width=800, height=700, \n",
" labels={'color':'RMSAD', 'x':'', 'y':'', 'z':''})"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## CLI - Grids and Random Samples\n",
"\n",
"Let's say you don't want to use Python, but rather would like to use the command line interface (CLI) to generate the grids and use them within, e.g., [Julia Language](https://julialang.org). The easiest way to do it is to output the grid to the common NumPy format, which you can then then load it in Julia using one of the packages, such as [NPZ.jl](https://www.juliapackages.com/p/npz).\n",
"\n",
"The commands are concise, simple, and fully described in both [documentation](https://amkrajewski.github.io/nimplex/) and CLI help:"
]
},
{
"cell_type": "code",
"execution_count": 32,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"\n",
"To run nimplex please either (1) provide no arguments and follow the prompts or \n",
"(2) use \"-c\" or \"--config\" to provide the configuration per instructions below:\n",
"\n",
"- Provide the 3-letter configuration for task type:\n",
" 1. Grid type or uniform random sampling:\n",
" - F: Full grid (including the simplex boundary)\n",
" - I: Internal grid (only points inside the simplex)\n",
" - R: Random/Monte Carlo uniform sampling over simplex.\n",
" - G: Graph (list of grid nodes and list of their neighbors)\n",
" 2. Fractional or Integer positions:\n",
" - F: Fractional grid/graph (points are normalized to fractions of 1)\n",
" - I: Integer grid/graph (points are integers)\n",
" 3. Print full result, its shape, or persist in a file:\n",
" - P: Print (presents full result as a table)\n",
" - S: Shape (only the shape / size information)\n",
" - N: Persist to NumPy array file (\"nimplex_<configFlags>.npy\" or \n",
" optionally a custom path as an additonal argument)\n",
"\n",
"- Followed by integers of (1) simplex dimension and (2) number of divisions or\n",
" samples depending on the task type. Optionally, custom output file path for \n",
" NumPy array can be provided as the last argument. E.g.:\n",
" -c FFS [simplex dimension] [number of divisions]\n",
" -c RFP [simplex dimension] [number of samples]\n",
" -c FIN [simplex dimension] [number of divisions] [path/to/outfile.npy]\n",
"\n",
"You can also utilize the following auxiliary flags:\n",
"--help | -h --> Show help.\n",
"--benchmark | -b --> Run benchmark for all tasks (9-dimensional space\n",
" with 12 divisions per dimension / 1M random samples).\n",
"\n"
]
}
],
"source": [
"!./nimplex --help"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Based on the above, we can quickly generate a nice `9`-component `I`nternal simplex grid with `F`ractional with `24` divisions per dimension and output it to `N`numpy format file `gridForJulia.npy`:"
]
},
{
"cell_type": "code",
"execution_count": 33,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Running with configuration:@[\"IFN\", \"9\", \"24\", \"gridForJulia.npy\"]\n",
"Persisting to NumPy array file:gridForJulia.npy\n",
"Shape:[490314, 9]\n"
]
}
],
"source": [
"!./nimplex --config IFN 9 24 gridForJulia.npy"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"And wihinin a couple hundred miliseconds, we should get around 490,000 points of the grid neatly stored in the file of 36MB (on 64-bit system), which we can now load it in Julia using\n",
"\n",
"```julia\n",
"using NPZ\n",
"data = npzread(\"gridForJulia.npy\")\n",
"```"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"In some cases, you may not have ability to read the NumPy format, beacuse for instance, you are writing code for your favorite satelite or train using a niche language like [Ada](https://ada-lang.io). For situations like that, the backup option of formatter text output is available. It is not nearly as efficient as the binary NumPy format, so the grid from the last example would take minutes to generate, but it should work with *everything*. \n",
"\n",
"Let's start by looking at a toy example. To get a small grid of `3`-component `F`ull simplex grid with `F`ractional with `5` divisions per dimension, we can do:"
]
},
{
"cell_type": "code",
"execution_count": 34,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Running with configuration:@[\"FFP\", \"3\", \"5\"]\n",
"Full Output:Tensor[system.float] of shape \"[21, 3]\" on backend \"Cpu\"\n",
"|0 0 1|\n",
"|0 0.2 0.8|\n",
"|0 0.4 0.6|\n",
"|0 0.6 0.4|\n",
"|0 0.8 0.2|\n",
"|0 1 0|\n",
"|0.2 0 0.8|\n",
"|0.2 0.2 0.6|\n",
"|0.2 0.4 0.4|\n",
"|0.2 0.6 0.2|\n",
"|0.2 0.8 0|\n",
"|0.4 0 0.6|\n",
"|0.4 0.2 0.4|\n",
"|0.4 0.4 0.2|\n",
"|0.4 0.6 0|\n",
"|0.6 0 0.4|\n",
"|0.6 0.2 0.2|\n",
"|0.6 0.4 0|\n",
"|0.8 0 0.2|\n",
"|0.8 0.2 0|\n",
"|1 0 0|\n"
]
}
],
"source": [
"!./nimplex --config FFP 3 5"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"As you can see, the first two lines of the output carry (1) task metadata on what was run to create the grid, (2) output metadata including its type(e.g., `int`/`float`/`float64`), shape, and backend. Then the grid itself is printed out in the form of a 2D array with each row representing a single point and structured as space-separated values between `|` characters. "
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"To get a larger grid, we may want to stream the output to a file rather than `P`rint it to the screen. We can do that by redirecting the output to a file using `>`. Let's create a `7`-component `F`ull simplex grid with `F`ractional with `12` divisions per dimension and output it to `gridForAda.txt`:"
]
},
{
"cell_type": "code",
"execution_count": 35,
"metadata": {},
"outputs": [],
"source": [
"!./nimplex --config FFP 7 12 > gridForAda.txt"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
",which you can quickly read in Ada using rather elaborate code to parse the file in strongly typed manner with some extra error checking. For the sake of conciseness, it is not shown here, but the below example shows how to do it in pure Python (just the built-in functions):"
]
},
{
"cell_type": "code",
"execution_count": 42,
"metadata": {},
"outputs": [],
"source": [
"with open('gridForAda.txt', 'r') as f:\n",
" gridForAda = f.read()\n",
" lines = gridForAda.replace('|', '').strip().split('\\n')\n",
" data = [[float(num) for num in line.split()] for line in lines[2:-1]]"
]
},
{
"cell_type": "code",
"execution_count": 43,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"[[0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 1.0],\n",
" [0.0, 0.0, 0.0, 0.0, 0.0, 0.0833333, 0.916667],\n",
" [0.0, 0.0, 0.0, 0.0, 0.0, 0.166667, 0.833333],\n",
" [0.0, 0.0, 0.0, 0.0, 0.0, 0.25, 0.75],\n",
" [0.0, 0.0, 0.0, 0.0, 0.0, 0.333333, 0.666667]]"
]
},
"execution_count": 43,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"data[:5]"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"And now, you are ready to go and use nimplex in your favorite language!"
]
}
],
"metadata": {
Expand Down

0 comments on commit 749bff7

Please sign in to comment.