diff --git a/.github/workflows/sphinx.yml b/.github/workflows/sphinx.yml new file mode 100644 index 00000000..656449db --- /dev/null +++ b/.github/workflows/sphinx.yml @@ -0,0 +1,172 @@ +# Deploy Sphinx. This could be shorter, but we also do some extra +# stuff. +# +# License: CC-0. This is the canonical location of this file, which +# you may want to link to anyway: +# https://github.com/coderefinery/sphinx-lesson-template/blob/main/.github/workflows/sphinx.yml +# https://raw.githubusercontent.com/coderefinery/sphinx-lesson-template/main/.github/workflows/sphinx.yml + + +name: sphinx +on: [push, pull_request] + +env: + DEFAULT_BRANCH: "master" + # If these SPHINXOPTS are enabled, then be strict about the + # builds and fail on any warnings. + #SPHINXOPTS: "-W --keep-going -T" + GENERATE_PDF: false # to enable, must be 'true' lowercase + GENERATE_SINGLEHTML: false # to enable, must be 'true' lowercase + PDF_FILENAME: lesson.pdf + MULTIBRANCH: false # to enable, must be 'true' lowercase + + +jobs: + build: + name: Build + runs-on: ubuntu-latest + permissions: + contents: read + + steps: + # https://github.com/marketplace/actions/checkout + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + lfs: true + + # https://github.com/marketplace/actions/setup-python + # ^-- This gives info on matrix testing. + - name: Install Python + uses: actions/setup-python@v3 + # with: + # python-version: '3.11' + # cache: 'pip' + + # https://docs.github.com/en/actions/guides/building-and-testing-python#installing-dependencies + # ^-- This gives info on installing dependencies with pip + - name: Install dependencies + run: | + python -m pip install --upgrade pip + if [ -f requirements.txt ]; then pip install -r requirements.txt; fi + python -m pip install sphinx numpy scipy matplotlib scikit-image numba yt geopack # add versions to matrix + + # Debug + - name: Debugging information + env: + ref: ${{github.ref}} + event_name: ${{github.event_name}} + head_ref: ${{github.head_ref}} + base_ref: ${{github.base_ref}} + run: | + echo "github.ref: ${ref}" + echo "github.event_name: ${event_name}" + echo "github.head_ref: ${head_ref}" + echo "github.base_ref: ${base_ref}" + echo "GENERATE_PDF: ${GENERATE_PDF}" + echo "GENERATE_SINGLEHTML: ${GENERATE_SINGLEHTML}" + set -x + git rev-parse --abbrev-ref HEAD + git branch + git branch -a + git remote -v + python -V + pip list --not-required + pip list + + + # Build + - uses: ammaraskar/sphinx-problem-matcher@master + - name: Build Sphinx docs (dirhtml) + # SPHINXOPTS used via environment variables + run: | + cd Documentation/sphinx/ + make dirhtml + # This fixes broken copy button icons, as explained in + # https://github.com/coderefinery/sphinx-lesson/issues/50 + # https://github.com/executablebooks/sphinx-copybutton/issues/110 + # This can be removed once these PRs are accepted (but the + # fixes also need to propagate to other themes): + # https://github.com/sphinx-doc/sphinx/pull/8524 + # https://github.com/readthedocs/sphinx_rtd_theme/pull/1025 + sed -i 's/url_root="#"/url_root=""/' _build/dirhtml/index.html || true + + # singlehtml + - name: Generate singlehtml + if: ${{ env.GENERATE_SINGLEHTML == 'true' }} + run: | + make singlehtml + mv _build/singlehtml/ _build/dirhtml/singlehtml/ + + # PDF if requested + - name: Generate PDF + if: ${{ env.GENERATE_PDF == 'true' }} + run: | + pip install https://github.com/rkdarst/sphinx_pyppeteer_builder/archive/refs/heads/main.zip + make pyppeteer + mv _build/pyppeteer/*.pdf _build/dirhtml/${PDF_FILENAME} + + # Stage all deployed assets in _gh-pages/ for simplicity, and to + # prepare to do a multi-branch deployment. + - name: Copy deployment data to _gh-pages/ + if: ${{ github.event_name == 'push' }} + run: + rsync -a Documentation/sphinx/_build/dirhtml/ _gh-pages/ + + # Use gh-pages-multibranch to multiplex different branches into + # one deployment. See + # https://github.com/coderefinery/gh-pages-multibranch + - name: gh-pages multibranch + uses: coderefinery/gh-pages-multibranch@main + if: ${{ github.event_name == 'push' && env.MULTIBRANCH == 'true' }} + with: + directory: _gh-pages/ + default_branch: ${{ env.DEFAULT_BRANCH }} + publish_branch: gh-pages + + # Add the .nojekyll file + - name: nojekyll + if: ${{ github.event_name == 'push' }} + run: | + touch _gh-pages/.nojekyll + + # Save artifact for the next step. + - uses: actions/upload-artifact@v4 + if: ${{ github.event_name == 'push' }} + with: + name: gh-pages-build + path: _gh-pages/ + + # Deploy in a separate job so that write permissions are restricted + # to the minimum steps. + deploy: + name: Deploy + runs-on: ubuntu-latest + needs: build + # This if can't use the env context - find better way later. + if: ${{ github.event_name == 'push' }} + permissions: + contents: write + + steps: + - uses: actions/download-artifact@v4 + if: ${{ github.event_name == 'push' && ( env.MULTIBRANCH == 'true' || github.ref == format('refs/heads/{0}', env.DEFAULT_BRANCH )) }} + with: + name: gh-pages-build + path: _gh-pages/ + + # As of 2023, we could publish to pages via a Deployment. This + # isn't done yet to give it time to stabilize (out of beta), and + # also having a gh-pages branch to check out is rather + # convenient. + + # Deploy + # https://github.com/peaceiris/actions-gh-pages + - name: Deploy + uses: peaceiris/actions-gh-pages@v3 + if: ${{ github.event_name == 'push' && ( env.MULTIBRANCH == 'true' || github.ref == format('refs/heads/{0}', env.DEFAULT_BRANCH )) }} + with: + publish_branch: gh-pages + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: _gh-pages/ + force_orphan: true diff --git a/Documentation/sphinx/Makefile b/Documentation/sphinx/Makefile new file mode 100644 index 00000000..d4bb2cbb --- /dev/null +++ b/Documentation/sphinx/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/Documentation/sphinx/about.rst b/Documentation/sphinx/about.rst new file mode 100644 index 00000000..9c23887e --- /dev/null +++ b/Documentation/sphinx/about.rst @@ -0,0 +1,8 @@ +.. about credits, etc + + +Credits +======= + +The pilot version of this automatic documentation was constructed by Sameli Siljamo during his two-week work-life trainee period. + diff --git a/Documentation/sphinx/biot_savart.rst b/Documentation/sphinx/biot_savart.rst new file mode 100644 index 00000000..b0829b03 --- /dev/null +++ b/Documentation/sphinx/biot_savart.rst @@ -0,0 +1,5 @@ +biot_savart +----------- + +.. automodule:: biot_savart + :members: \ No newline at end of file diff --git a/Documentation/sphinx/calculations.rst b/Documentation/sphinx/calculations.rst new file mode 100644 index 00000000..a9ac10db --- /dev/null +++ b/Documentation/sphinx/calculations.rst @@ -0,0 +1,6 @@ +calculations +================================= + +.. automodule:: pytools.calculations + :members: + :imported-members: diff --git a/Documentation/sphinx/conf.py b/Documentation/sphinx/conf.py new file mode 100644 index 00000000..ae099ee1 --- /dev/null +++ b/Documentation/sphinx/conf.py @@ -0,0 +1,36 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +import sys +from pathlib import Path + +sys.path.insert(0, str(Path('..', '..').resolve())) +sys.path.insert(0, str(Path('..', '..', 'scripts').resolve())) +print(str(Path('..','..').resolve())) +print(str(Path('..','..', 'scripts').resolve())) +project = 'analysator' +copyright = '2024, University of Helsinki' +author = 'Sameli' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + 'sphinx.ext.autodoc' + ] + +templates_path = ['_templates'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'alabaster' +html_static_path = ['_static'] diff --git a/Documentation/sphinx/fetchscripts.py b/Documentation/sphinx/fetchscripts.py new file mode 100644 index 00000000..9c01e444 --- /dev/null +++ b/Documentation/sphinx/fetchscripts.py @@ -0,0 +1,19 @@ +import glob +import os + +files = glob.glob('C:/Users/samel/OneDrive/Tiedostot/TET/analysator/scripts/*.py') + +for file in files: + file = os.path.basename(file)[:-3] + print(file) + with open('scripts.rst', 'a') as f: + f.write(file + "\n") + f.write("-"*len(file)+ "\n") + f.write("\n" + ".. automodule:: " + (file) + "\n") + f.write("\n" + "------------\n\n") + + # with open(file + '.rst', 'w') as f: + # f.write(file + "\n") + # f.write("-"*len(file)+ "\n") + # f.write("\n" + ".. automodule:: " + (file) + "\n") + # f.write("\t:members:") diff --git a/Documentation/sphinx/gics.rst b/Documentation/sphinx/gics.rst new file mode 100644 index 00000000..1dcdebf1 --- /dev/null +++ b/Documentation/sphinx/gics.rst @@ -0,0 +1,5 @@ +gics +---- + +.. automodule:: gics + :members: \ No newline at end of file diff --git a/Documentation/sphinx/index.rst b/Documentation/sphinx/index.rst new file mode 100644 index 00000000..2a41013b --- /dev/null +++ b/Documentation/sphinx/index.rst @@ -0,0 +1,40 @@ +.. analysator documentation master file, created by + sphinx-quickstart on Tue Oct 29 10:43:26 2024. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +analysator documentation +======================== + +`Analysator `_ is a set of Python tools and scripts used to read and analyze `Vlasiator `_ output files (`VLSV `_). Vlasiator and its related tools are developed at `University of Helsinki `_, and are open source. + +.. image:: logo_color.png + :height: 37 + :width: 300 + :scale: 75 + :align: right + :alt: Vlasiator Logo + + +This documentation is generated via Sphinx-autodoc from Analysator source. This page is a work in progress, with docstrings and the documentation layout in flux. Contributions via Analysator repo are welcome. + +Add your content using ``reStructuredText`` syntax. See the +`reStructuredText `_ +documentation for details. + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + plot + calculations + vlsvfile + miscellaneous + scripts + about + +.. automodule:: pytools + :members: + :imported-members: + :undoc-members: + diff --git a/Documentation/sphinx/logo_color.png b/Documentation/sphinx/logo_color.png new file mode 100644 index 00000000..3bd85b59 Binary files /dev/null and b/Documentation/sphinx/logo_color.png differ diff --git a/Documentation/sphinx/magnetopause2d.rst b/Documentation/sphinx/magnetopause2d.rst new file mode 100644 index 00000000..8e1717f1 --- /dev/null +++ b/Documentation/sphinx/magnetopause2d.rst @@ -0,0 +1,5 @@ +magnetopause2d +-------------- + +.. automodule:: magnetopause2d + :members: \ No newline at end of file diff --git a/Documentation/sphinx/magnetopause3d.rst b/Documentation/sphinx/magnetopause3d.rst new file mode 100644 index 00000000..7d90752f --- /dev/null +++ b/Documentation/sphinx/magnetopause3d.rst @@ -0,0 +1,5 @@ +magnetopause3d +-------------- + +.. automodule:: magnetopause3d + :members: \ No newline at end of file diff --git a/Documentation/sphinx/make.bat b/Documentation/sphinx/make.bat new file mode 100644 index 00000000..954237b9 --- /dev/null +++ b/Documentation/sphinx/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/Documentation/sphinx/miscellaneous.rst b/Documentation/sphinx/miscellaneous.rst new file mode 100644 index 00000000..7a7e9bf8 --- /dev/null +++ b/Documentation/sphinx/miscellaneous.rst @@ -0,0 +1,6 @@ +miscellaneous +================================== + +.. automodule:: pytools.miscellaneous + :members: + :imported-members: diff --git a/Documentation/sphinx/plot.rst b/Documentation/sphinx/plot.rst new file mode 100644 index 00000000..f0b19c91 --- /dev/null +++ b/Documentation/sphinx/plot.rst @@ -0,0 +1,8 @@ +plot +============================ + +.. automodule:: pytools.plot + :members: + :exclude-members: Version + :imported-members: + diff --git a/Documentation/sphinx/scripts.rst b/Documentation/sphinx/scripts.rst new file mode 100644 index 00000000..6da5198f --- /dev/null +++ b/Documentation/sphinx/scripts.rst @@ -0,0 +1,70 @@ +scripts +===================== + +Scripts are not included in the main Analysator module import; instead, these are separate scripts utilising Analysator to some purpose. + +biot_savart +----------- +:doc:`biot_savart` + +.. automodule:: biot_savart + :no-index: + +------------ + +gics +---- +:doc:`gics` + +.. automodule:: gics + :no-index: + +------------ + +magnetopause2d +-------------- +:doc:`magnetopause2d` + +.. automodule:: magnetopause2d + :no-index: + +------------ + +magnetopause3d +-------------- +:doc:`magnetopause3d` + +.. automodule:: magnetopause3d + :no-index: + +------------ + +shue +-------------- +:doc:`shue` + +.. automodule:: shue + :no-index: + +------------ + +tsyganenko +-------------- +:doc:`tsyganenko` + +.. automodule:: tsyganenko + :no-index: + +------------ + +.. toctree:: + :maxdepth: 2 + :caption: Scripts: + + biot_savart + gics + magnetopause2d + magnetopause3d + shue + tsyganenko + diff --git a/Documentation/sphinx/shue.rst b/Documentation/sphinx/shue.rst new file mode 100644 index 00000000..362c0fa9 --- /dev/null +++ b/Documentation/sphinx/shue.rst @@ -0,0 +1,5 @@ +shue +---- + +.. automodule:: shue + :members: \ No newline at end of file diff --git a/Documentation/sphinx/tsyganenko.rst b/Documentation/sphinx/tsyganenko.rst new file mode 100644 index 00000000..7804f48c --- /dev/null +++ b/Documentation/sphinx/tsyganenko.rst @@ -0,0 +1,5 @@ +tsyganenko +---------- + +.. automodule:: tsyganenko + :members: \ No newline at end of file diff --git a/Documentation/sphinx/vlsvfile.rst b/Documentation/sphinx/vlsvfile.rst new file mode 100644 index 00000000..6fcf3ea2 --- /dev/null +++ b/Documentation/sphinx/vlsvfile.rst @@ -0,0 +1,8 @@ +vlsvfile +============================ + +VlsvFile is responsibe for implementing read and write functionality for the vlsv format, as well as defining data reducers and reduction pipelines. Some of this will be likely moved around to be more modular in some indefinite point in the future. + +.. automodule:: pytools.vlsvfile + :members: + :imported-members: diff --git a/miscellaneous/filenames.py b/miscellaneous/filenames.py index 7ba67f73..35ff23bf 100644 --- a/miscellaneous/filenames.py +++ b/miscellaneous/filenames.py @@ -21,17 +21,18 @@ # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. # -import glob -import os - '''@package docstring This module imports glob and os and has some miscellaneous functions for basic file manipulation ''' +import glob +import os + def get_sorted_file_names(name="*.vlsv"): - '''Gets the file names in the current directory and sorts them. - :param name: Name of the file(s), for example "*.vlsv" - :returns: a list of file names in sorted order + ''' Gets the file names in the current directory and sorts them. + + :param name: Name of the file(s), for example `"*.vlsv"` + :returns: a list of file names in sorted order ''' fileNames=glob.glob(name) fileNames.sort() diff --git a/pyCalculations/fieldtracer.py b/pyCalculations/fieldtracer.py index 6e7bf5b6..9c7bd0fb 100644 --- a/pyCalculations/fieldtracer.py +++ b/pyCalculations/fieldtracer.py @@ -311,12 +311,18 @@ def static_field_tracer_3d( vlsvReader, seed_coords, max_iterations, dx, directi Code uses forward Euler method to conduct the tracing. Based on Analysator's static_field_tracer() :Inputs: + param vlsvReader: A vlsvReader object (~an open .vlsv file) - param coord_list: a list of 3-element array-like initial coordinates [ [x1,y1,z1], [x2,y2,z2], ... ] + + param coord_list: a list of 3-element array-like initial coordinates [ [x1,y1,z1], [x2,y2,z2], ... ] :: if considering just a single starting point, the code accepts a 3-element array-like object [x1,y1,z1] + param max_iterations: The maximum number of iterations (int) before the algorithm stops. Total traced length is dx*max_iterations + param dx: One iteration step length [meters] (ex. dx=1e4 for typical applications) + keyword direction: '+' or '-' or '+-' Follow field in the plus direction, minus direction, or both + keyword grid_var: Variable to be traced (A string) options include: grid_var = some string @@ -328,14 +334,19 @@ def static_field_tracer_3d( vlsvReader, seed_coords, max_iterations, dx, directi ex. fg = vlsvobj.read_variable('fg_b') field grid data is already loaded externally using read_variable() method (see vlsvreader.py). If fg keyword is set this way, the input vlsvReader is only referred to for metadata (esp. grid dimensions) - keyword stop_condition: Boolean array (seed_coords.shape[0],) + + keyword stop_condition: Boolean array (seed_coords.shape[0],) + Determine when the iteration stop, for the vg trace only If not specified, it will always be True for each seed points. eg. def my_stop(points): + distances = np.linalg.norm(points[:,:],axis = 1) return (distances <= lower_bound) | (distances >= upper_bound) + :returns: points_traced --- a 3d numpy array [len(seed_coords),max_iterations (or 2*max_iterations-1 for '+-'),3] Non-traced sections (e.g. iterations after reaching outer boundaries) filled with np.nan + keyword centering: Set to a string ('face' or 'edge') indicating whether the fg variable is face- or edge-centered If keyword fg == 'fg_b', then centering = 'face' (overriding input) If keyword fg == 'fg_e', then centering = 'edge' (overriding input) diff --git a/pyCalculations/interpolator_amr.py b/pyCalculations/interpolator_amr.py index 30cf1d28..ea15d07f 100644 --- a/pyCalculations/interpolator_amr.py +++ b/pyCalculations/interpolator_amr.py @@ -218,6 +218,7 @@ def __call__(self, pt, cellids = None): class AMRInterpolator(object): ''' Wrapper class for interpolators, esp. at refinement interfaces. Supported methods: + linear - (nearly) C0 continuous, regular-grid trilinear interpolant extended to collapsed hexahedral cells. - Non-parametric diff --git a/pyCalculations/intpol_file.py b/pyCalculations/intpol_file.py index 145759fc..56d8ffc2 100644 --- a/pyCalculations/intpol_file.py +++ b/pyCalculations/intpol_file.py @@ -32,7 +32,9 @@ def vlsv_intpol_file(file_vlsv,file_orbit,varlist,file_output): :param varlist: Variable list :param file_output: Output ascii file (columns: x,y,z,cellid,var1,var2,var3,...) :returns: none + .. code-block:: python + # Example: import pytools as pt pt.calculations.vlsv_intpol_file("state00040000.vlsv","orbit.dat",["cellB","n_H+sw_ave"],"output.dat") diff --git a/pyCalculations/intpol_points.py b/pyCalculations/intpol_points.py index 370c7b0a..4a6fdc19 100644 --- a/pyCalculations/intpol_points.py +++ b/pyCalculations/intpol_points.py @@ -34,7 +34,9 @@ def vlsv_intpol_points(vlsvReader,points,varlist,operator="pass",interpolation_o :param operator: The operator for the variable, for example "x" for x-component or "magnitude" for magnitude :param interpolation_order: Order of interpolation (0 or 1), defaults to 1 :returns: A tuple with output: (coordinates,variable_values,header_string) + .. code-block:: python + # Example: import pytools as pt import numpy as np diff --git a/pyCalculations/non_maxwellianity.py b/pyCalculations/non_maxwellianity.py index 1a0d37a4..0802bb74 100644 --- a/pyCalculations/non_maxwellianity.py +++ b/pyCalculations/non_maxwellianity.py @@ -29,7 +29,7 @@ def epsilon_M(f,cell,pop="proton",m=m_p, bulk=None, B=None, :returns: scalar, non-Maxwellianity parameter for given model and norm The definition is given by Graham et al. (2021): - (1/2n) * integral(|f_i - g_M|) d^3v + (1/2n) * integral(\\|f_i - g_M\\|) d^3v valued between 0 (bi-Maxwellian) and 1 (complete deviation from a bi-Maxwellian). diff --git a/pyCalculations/pitchangle.py b/pyCalculations/pitchangle.py index e4940753..d8296c98 100644 --- a/pyCalculations/pitchangle.py +++ b/pyCalculations/pitchangle.py @@ -41,43 +41,43 @@ def pitch_angles( vlsvReader, ''' Calculates the pitch angle distribution for a given cell - :param vlsvReader: Some VlsvReader class with a file open. Can be overriden by keywords. - :param cellid: The cell id whose pitch angle the user wants - NOTE: The cell id must have a velocity distribution! - :kword filename: path to .vlsv file to use for input. - :kword filedir: Optionally provide directory where files are located and use step for bulk file name - :kword step: output step index, used for constructing output (and possibly input) filename - - :kword nbins: How many bins to use for the distribution - :kword cosine: True if returning the pitch angles as a cosine(alpha) plot [-1,1]. - If false, returns as pitch angle in degrees [0,180]. - - :kword plasmaframe: True if the user wants to get the pitch angle distribution - in the plasma frame (for this population). - If set to a string, will try to use the string as a variable for - the frame to transform into. - If set to a 3-element vector, will use that frame instead. - - :kword vcut: Set to True to ignore velocity cells below 2x the thermal speed. - If set to a number, will use that velocity in m/s instead. - :kword vcutmax: Set to True to ignore velocity cells above 2x the thermal speed. - If set to a number, will use that velocity in m/s instead. - - :kword outputdir: Optional (recommended) method to save results to a file in the given directory. - If directory does not exist, it will be created. Filenames within directory are - generated automatically. - :kword outputfile: Provide exact output file name (including complete path) - - :kword pop: Active population, defaults to proton (avgs) - - :returns: pitch angles and avgs [pitch_angles, avgs] - - .. code-block:: python - - # Example usage: - vlsvReader = VlsvReader("restart.0000798.vlsv") - result = pitch_angles( vlsvReader=vlsvReader, 1924, cosine=True, - plasmaframe=True, outputdir="/wrk/username/pitchangledirectory/" ) + :param vlsvReader: Some VlsvReader class with a file open. Can be overriden by keywords. + :param cellid: The cell id whose pitch angle the user wants + NOTE: The cell id must have a velocity distribution! + :kword filename: path to .vlsv file to use for input. + :kword filedir: Optionally provide directory where files are located and use step for bulk file name + :kword step: output step index, used for constructing output (and possibly input) filename + + :kword nbins: How many bins to use for the distribution + :kword cosine: True if returning the pitch angles as a cosine(alpha) plot [-1,1]. + If false, returns as pitch angle in degrees [0,180]. + + :kword plasmaframe: True if the user wants to get the pitch angle distribution + in the plasma frame (for this population). + If set to a string, will try to use the string as a variable for + the frame to transform into. + If set to a 3-element vector, will use that frame instead. + + :kword vcut: Set to True to ignore velocity cells below 2x the thermal speed. + If set to a number, will use that velocity in m/s instead. + :kword vcutmax: Set to True to ignore velocity cells above 2x the thermal speed. + If set to a number, will use that velocity in m/s instead. + + :kword outputdir: Optional (recommended) method to save results to a file in the given directory. + If directory does not exist, it will be created. Filenames within directory are + generated automatically. + :kword outputfile: Provide exact output file name (including complete path) + + :kword pop: Active population, defaults to proton (avgs) + + :returns: pitch angles and avgs [pitch_angles, avgs] + + .. code-block:: python + + # Example usage: + vlsvReader = VlsvReader("restart.0000798.vlsv") + result = pitch_angles( vlsvReader=vlsvReader, 1924, cosine=True, + plasmaframe=True, outputdir="/wrk/username/pitchangledirectory/" ) ''' # Input file or object diff --git a/pyCalculations/variable.py b/pyCalculations/variable.py index d09eefa7..abba1ee8 100644 --- a/pyCalculations/variable.py +++ b/pyCalculations/variable.py @@ -89,8 +89,6 @@ def get_scaled_units(self, vscale=None, env='EarthSpace', manualDict=None): :param vscale: float, factor to scale the variable with :returns: (norming factor, scaledUnits, scaledLatexUnits) - .. note:: - ''' # @@ -217,7 +215,6 @@ def get_scaled_var(self, vscale=None, data=None, env='EarthSpace', manualDict=No :param manualDict: a dictionary of {units : {scalingparams}}; used to update the included dictionary :returns: self, with scaled units with pre-formatted units included in the varinfo. - .. note:: ''' diff --git a/pyPlots/plot_colormap.py b/pyPlots/plot_colormap.py index 0dacabfe..2717c046 100644 --- a/pyPlots/plot_colormap.py +++ b/pyPlots/plot_colormap.py @@ -75,151 +75,151 @@ def plot_colormap(filename=None, ''' Plots a coloured plot with axes and a colour bar. - :kword filename: path to .vlsv file to use for input. Assumes a bulk file. - :kword vlsvobj: Optionally provide a python vlsvfile object instead - :kword filedir: Optionally provide directory where files are located and use step for bulk file name - :kword step: output step index, used for constructing output (and possibly input) filename - :kword outputdir: path to directory where output files are created (default: $HOME/Plots/ or override with PTOUTPUTDIR) - If directory does not exist, it will be created. If the string does not end in a - forward slash, the final part will be used as a prefix for the files. - :kword outputfile: Singular output file name - - :kword nooverwrite: Set to only perform actions if the target output file does not yet exist - - :kword var: variable to plot, e.g. rho, RhoBackstream, beta, Temperature, MA, Mms, va, vms, - E, B, v, V or others. Accepts any variable known by analysator/pytools. - Per-population variables are simply given as "proton/rho" etc - :kword operator: Operator to apply to variable: None, x, y, or z. Vector variables return either - the queried component, or otherwise the magnitude. - :kword op: duplicate of operator - - :kword boxm: zoom box extents [x0,x1,y0,y1] in metres (default and truncate to: whole simulation box) - :kword boxre: zoom box extents [x0,x1,y0,y1] in Earth radii (default and truncate to: whole simulation box) - :kword colormap: colour scale for plot, use e.g. hot_desaturated, jet, viridis, plasma, inferno, - magma, parula, nipy_spectral, RdBu, bwr - :kword run: run identifier, used for constructing output filename - :kword title: string to use as plot title instead of time. - Special case: Set to "msec" to plot time with millisecond accuracy or "musec" - for microsecond accuracy. "sec" is integer second accuracy. - :kword cbtitle: string to use as colorbar title instead of map name - :kword axisunit: Plot axes using 10^{axisunit} m (default: Earth radius R_E) - :kword tickinterval: Interval at which to have ticks on axes (not colorbar) - - :kwird usesci: Use scientific notation for colorbar ticks? (default: True) - :kword vmin,vmax: min and max values for colour scale and colour bar. If no values are given, - min and max values for whole plot (non-zero rho regions only) are used. - :kword symmetric: Set the absolute value of vmin and vmax to the greater of the two - :kword lin: Flag for using linear colour scaling instead of log. If an integer, defines number - of colorbar ticks. - :kword symlog: Use logarithmic scaling, but linear when abs(value) is below the value given to symlog. - Allows symmetric quasi-logarithmic plots of e.g. transverse field components. - A given of 0 or True translates to a threshold of max(abs(vmin),abs(vmax)) * 1.e-2, but this can - result in the innermost tick marks overlapping. In this case, using a larger value for - symlog is suggested. - :kword wmark: If set to non-zero, will plot a Vlasiator watermark in the top left corner. If set to a text - string, tries to use that as the location, e.g. "NW","NE","SW","SW" - :kword wmarkb: As for wmark, but uses an all-black Vlasiator logo. - :kword Earth: If set, draws an earth at (0,0) - :kword highres: Creates the image in high resolution, scaled up by this value (suitable for print). - - :kword draw: Set to anything but None or False in order to draw image on-screen instead of saving to file (requires x-windowing) - - :kword noborder: Plot figure edge-to-edge without borders (default off) - :kword noxlabels: Suppress x-axis labels and title - :kword noylabels: Suppress y-axis labels and title - :kword scale: Scale text size (default=1.0) - :kword thick: line and axis thickness, default=1.0 - :kword nocb: Set to suppress drawing of colourbar - :kword internalcb: Set to draw colorbar inside plot instead of outside. If set to a text - string, tries to use that as the location, e.g. "NW","NE","SW","SW" - - :kword external: Optional function to use for external plotting of e.g. contours. The function - receives the following arguments: ax, XmeshXY,YmeshXY, pass_maps - If the function accepts a fifth variable, if set to true, it is expected to - return a list of required variables for constructing the pass_maps dictionary. - :kword expression: Optional function which calculates a custom expression to plot. The function - receives the same dictionary of numpy arrays as external, as an argument pass_maps, - the contents of which are maps of variables. Each is either of size [ysize,xsize] - or for multi-dimensional variables (vectors, tensors) it's [ysize,xsize,dim]. - If the function accepts a second variable, if set to true, it is expected to - return a list of required variables for pass_maps. - :kword diff: Instead of a regular plot, plot the difference between the selected plot type for - the regular source file and the file given by this keyword. This overides external - and expression keywords, as well as related pass_vars, pass_times, and pass_full. - - Important note: the dictionaries of arrays passed to external and expression are of shape [ysize,xzize], so - for some analysis transposing them is necessary. For pre-existing functions to use and to base new functions - on, see the plot_helpers.py file. - - :kword vscale: Scale all values with this before plotting. Useful for going from e.g. m^-3 to cm^-3 - or from tesla to nanotesla. Guesses correct units for colourbar for some known - variables. Set to None to search for a default scaling settings. - :kword absolute: Plot the absolute of the evaluated variable - - :kword pass_vars: Optional list of map names to pass to the external/expression functions - as a dictionary of numpy arrays. Each is either of size [ysize,xsize] or - for multi-dimensional variables (vectors, tensors) it's [ysize,xsize,dim]. - :kword pass_times: Integer, how many timesteps in each direction should be passed to external/expression - functions in pass_vars (e.g. pass_times=1 passes the values of three timesteps). If - pass_times has two values, the first is the extent before, the second after. - (e.g. pass_times=[2,1] passes the values of two preceding and one following timesteps - for a total of four timesteps) - This causes pass_vars to become a list of timesteps, with each timestep containing - a dictionary of numpy arrays as for regular pass_vars. An additional dictionary entry is - added as 'dstep' which gives the timestep offset from the master frame. - Does not work if working from a vlsv-object. - :kword pass_full: Set to anything but None in order to pass the full arrays instead of a zoomed-in section - - :kword fluxfile: Filename to plot fluxfunction from - :kword flux_levels: A list of flux function values to plot as the contours (default: None, a set of constant - intervals: np.linspace(-10,10,fluxlines*60)) - :kword fluxdir: Directory in which fluxfunction files can be found - :kword fluxthick: Scale fluxfunction line thickness - :kword fluxlines: Relative density of fluxfunction contours - :kword fsaved: Overplot locations of fSaved. If keyword is set to a string, that will be the colour used. - :kword nomask: Do not mask plotting based on proton density - - :kword vectors: Set to a vector variable to overplot (unit length vectors, color displays variable magnitude) - :kword vectordensity: Aim for how many vectors to show in plot window (default 100) - :kword vectorcolormap: Colormap to use for overplotted vectors (default: gray) - :kword vectorsize: Scaling of vector sizes - - :kword streamlines: Set to a vector variable to overplot as streamlines - :kword streamlinedensity: Set streamline density (default 1) - :kword streamlinecolor: Set streamline color (default white) - :kword streamlinethick: Set streamline thickness - - :kword axes: Provide the routine a set of axes to draw within instead of generating a new image. - It is recommended to either also provide cbaxes or activate nocb, unless one wants a colorbar - to be automatically added next to the panel (but this may affect the overall layout) - Note that the aspect ratio of the colormap is made equal in any case, hence the axes - proportions may change if the box and axes size are not designed to match by the user - :kword cbaxes: Provide the routine a set of axes for the colourbar. - :kword useimshow: Use imshow for raster background instead (default: False) - :kword imshowinterp: Use this matplotlib interpolation for imshow (default: 'none') - - :returns: Outputs an image to a file or to the screen. - - .. code-block:: python - - # Example usage: - plot_colormap(filename=fileLocation, var="MA", run="BCQ", - colormap='nipy_spectral',step=j, outputdir=outputLocation, - lin=True, wmark=1, vmin=2.7, vmax=10, - external=cavitoncontours, pass_vars=['rho','B','beta']) - # Where cavitoncontours is an external function which receives the arguments - # ax, XmeshXY,YmeshXY, pass_maps - # where pass_maps is a dictionary of maps for the requested variables. - - # example (simple) use of expressions: - def exprMA_cust(exprmaps, requestvariables=False): - if requestvariables==True: - return ['va'] - custombulkspeed=750000. # m/s - va = exprmaps['va'][:,:] - MA = custombulkspeed/va - return MA - plot_colormap(filename=fileLocation, vmin=1 vmax=40, expression=exprMA_cust,lin=True) + :kword filename: path to .vlsv file to use for input. Assumes a bulk file. + :kword vlsvobj: Optionally provide a python vlsvfile object instead + :kword filedir: Optionally provide directory where files are located and use step for bulk file name + :kword step: output step index, used for constructing output (and possibly input) filename + :kword outputdir: path to directory where output files are created (default: $HOME/Plots/ or override with PTOUTPUTDIR) + If directory does not exist, it will be created. If the string does not end in a + forward slash, the final part will be used as a prefix for the files. + :kword outputfile: Singular output file name + + :kword nooverwrite: Set to only perform actions if the target output file does not yet exist + + :kword var: variable to plot, e.g. rho, RhoBackstream, beta, Temperature, MA, Mms, va, vms, + E, B, v, V or others. Accepts any variable known by analysator/pytools. + Per-population variables are simply given as "proton/rho" etc + :kword operator: Operator to apply to variable: None, x, y, or z. Vector variables return either + the queried component, or otherwise the magnitude. + :kword op: duplicate of operator + + :kword boxm: zoom box extents [x0,x1,y0,y1] in metres (default and truncate to: whole simulation box) + :kword boxre: zoom box extents [x0,x1,y0,y1] in Earth radii (default and truncate to: whole simulation box) + :kword colormap: colour scale for plot, use e.g. hot_desaturated, jet, viridis, plasma, inferno, + magma, parula, nipy_spectral, RdBu, bwr + :kword run: run identifier, used for constructing output filename + :kword title: string to use as plot title instead of time. + Special case: Set to "msec" to plot time with millisecond accuracy or "musec" + for microsecond accuracy. "sec" is integer second accuracy. + :kword cbtitle: string to use as colorbar title instead of map name + :kword axisunit: Plot axes using 10^{axisunit} m (default: Earth radius R_E) + :kword tickinterval: Interval at which to have ticks on axes (not colorbar) + + :kwird usesci: Use scientific notation for colorbar ticks? (default: True) + :kword vmin,vmax: min and max values for colour scale and colour bar. If no values are given, + min and max values for whole plot (non-zero rho regions only) are used. + :kword symmetric: Set the absolute value of vmin and vmax to the greater of the two + :kword lin: Flag for using linear colour scaling instead of log. If an integer, defines number + of colorbar ticks. + :kword symlog: Use logarithmic scaling, but linear when abs(value) is below the value given to symlog. + Allows symmetric quasi-logarithmic plots of e.g. transverse field components. + A given of 0 or True translates to a threshold of max(abs(vmin),abs(vmax)) * 1.e-2, but this can + result in the innermost tick marks overlapping. In this case, using a larger value for + symlog is suggested. + :kword wmark: If set to non-zero, will plot a Vlasiator watermark in the top left corner. If set to a text + string, tries to use that as the location, e.g. "NW","NE","SW","SW" + :kword wmarkb: As for wmark, but uses an all-black Vlasiator logo. + :kword Earth: If set, draws an earth at (0,0) + :kword highres: Creates the image in high resolution, scaled up by this value (suitable for print). + + :kword draw: Set to anything but None or False in order to draw image on-screen instead of saving to file (requires x-windowing) + + :kword noborder: Plot figure edge-to-edge without borders (default off) + :kword noxlabels: Suppress x-axis labels and title + :kword noylabels: Suppress y-axis labels and title + :kword scale: Scale text size (default=1.0) + :kword thick: line and axis thickness, default=1.0 + :kword nocb: Set to suppress drawing of colourbar + :kword internalcb: Set to draw colorbar inside plot instead of outside. If set to a text + string, tries to use that as the location, e.g. "NW","NE","SW","SW" + + :kword external: Optional function to use for external plotting of e.g. contours. The function + receives the following arguments: ax, XmeshXY,YmeshXY, pass_maps + If the function accepts a fifth variable, if set to true, it is expected to + return a list of required variables for constructing the pass_maps dictionary. + :kword expression: Optional function which calculates a custom expression to plot. The function + receives the same dictionary of numpy arrays as external, as an argument pass_maps, + the contents of which are maps of variables. Each is either of size [ysize,xsize] + or for multi-dimensional variables (vectors, tensors) it's [ysize,xsize,dim]. + If the function accepts a second variable, if set to true, it is expected to + return a list of required variables for pass_maps. + :kword diff: Instead of a regular plot, plot the difference between the selected plot type for + the regular source file and the file given by this keyword. This overides external + and expression keywords, as well as related pass_vars, pass_times, and pass_full. + + Important note: the dictionaries of arrays passed to external and expression are of shape [ysize,xzize], so + for some analysis transposing them is necessary. For pre-existing functions to use and to base new functions + on, see the plot_helpers.py file. + + :kword vscale: Scale all values with this before plotting. Useful for going from e.g. m^-3 to cm^-3 + or from tesla to nanotesla. Guesses correct units for colourbar for some known + variables. Set to None to search for a default scaling settings. + :kword absolute: Plot the absolute of the evaluated variable + + :kword pass_vars: Optional list of map names to pass to the external/expression functions + as a dictionary of numpy arrays. Each is either of size [ysize,xsize] or + for multi-dimensional variables (vectors, tensors) it's [ysize,xsize,dim]. + :kword pass_times: Integer, how many timesteps in each direction should be passed to external/expression + functions in pass_vars (e.g. pass_times=1 passes the values of three timesteps). If + pass_times has two values, the first is the extent before, the second after. + (e.g. pass_times=[2,1] passes the values of two preceding and one following timesteps + for a total of four timesteps) + This causes pass_vars to become a list of timesteps, with each timestep containing + a dictionary of numpy arrays as for regular pass_vars. An additional dictionary entry is + added as 'dstep' which gives the timestep offset from the master frame. + Does not work if working from a vlsv-object. + :kword pass_full: Set to anything but None in order to pass the full arrays instead of a zoomed-in section + + :kword fluxfile: Filename to plot fluxfunction from + :kword flux_levels: A list of flux function values to plot as the contours (default: None, a set of constant + intervals: np.linspace(-10,10,fluxlines*60)) + :kword fluxdir: Directory in which fluxfunction files can be found + :kword fluxthick: Scale fluxfunction line thickness + :kword fluxlines: Relative density of fluxfunction contours + :kword fsaved: Overplot locations of fSaved. If keyword is set to a string, that will be the colour used. + :kword nomask: Do not mask plotting based on proton density + + :kword vectors: Set to a vector variable to overplot (unit length vectors, color displays variable magnitude) + :kword vectordensity: Aim for how many vectors to show in plot window (default 100) + :kword vectorcolormap: Colormap to use for overplotted vectors (default: gray) + :kword vectorsize: Scaling of vector sizes + + :kword streamlines: Set to a vector variable to overplot as streamlines + :kword streamlinedensity: Set streamline density (default 1) + :kword streamlinecolor: Set streamline color (default white) + :kword streamlinethick: Set streamline thickness + + :kword axes: Provide the routine a set of axes to draw within instead of generating a new image. + It is recommended to either also provide cbaxes or activate nocb, unless one wants a colorbar + to be automatically added next to the panel (but this may affect the overall layout) + Note that the aspect ratio of the colormap is made equal in any case, hence the axes + proportions may change if the box and axes size are not designed to match by the user + :kword cbaxes: Provide the routine a set of axes for the colourbar. + :kword useimshow: Use imshow for raster background instead (default: False) + :kword imshowinterp: Use this matplotlib interpolation for imshow (default: 'none') + + :returns: Outputs an image to a file or to the screen. + + .. code-block:: python + + # Example usage: + plot_colormap(filename=fileLocation, var="MA", run="BCQ", + colormap='nipy_spectral',step=j, outputdir=outputLocation, + lin=True, wmark=1, vmin=2.7, vmax=10, + external=cavitoncontours, pass_vars=['rho','B','beta']) + # Where cavitoncontours is an external function which receives the arguments + # ax, XmeshXY,YmeshXY, pass_maps + # where pass_maps is a dictionary of maps for the requested variables. + + # example (simple) use of expressions: + def exprMA_cust(exprmaps, requestvariables=False): + if requestvariables==True: + return ['va'] + custombulkspeed=750000. # m/s + va = exprmaps['va'][:,:] + MA = custombulkspeed/va + return MA + plot_colormap(filename=fileLocation, vmin=1 vmax=40, expression=exprMA_cust,lin=True) ''' diff --git a/pyPlots/plot_colormap3dslice.py b/pyPlots/plot_colormap3dslice.py index 77716b5b..4cafd298 100644 --- a/pyPlots/plot_colormap3dslice.py +++ b/pyPlots/plot_colormap3dslice.py @@ -77,150 +77,150 @@ def plot_colormap3dslice(filename=None, ''' Plots a coloured plot with axes and a colour bar. - :kword filename: path to .vlsv file to use for input. Assumes a bulk file. - :kword vlsvobj: Optionally provide a python vlsvfile object instead - :kword filedir: Optionally provide directory where files are located and use step for bulk file name - :kword step: output step index, used for constructing output (and possibly input) filename - :kword run: run identifier, used for constructing output filename - :kword outputdir: path to directory where output files are created (default: $HOME/Plots/ or override with PTOUTPUTDIR) - If directory does not exist, it will be created. If the string does not end in a - forward slash, the final part will be used as a prefix for the files. - :kword outputfile: Singular output file name - - :kword nooverwrite: Set to only perform actions if the target output file does not yet exist - - :kword var: variable to plot, e.g. rho, RhoBackstream, beta, Temperature, MA, Mms, va, vms, - E, B, v, V or others. Accepts any variable known by analysator/pytools. - Per-population variables are simply given as "proton/rho" etc - :kword operator: Operator to apply to variable: None, x, y, or z. Vector variables return either - the queried component, or otherwise the magnitude. - :kword op: duplicate of operator - - :kword boxm: zoom box extents [x0,x1,y0,y1] in metres (default and truncate to: whole simulation box) - :kword boxre: zoom box extents [x0,x1,y0,y1] in Earth radii (default and truncate to: whole simulation box) - :kword colormap: colour scale for plot, use e.g. hot_desaturated, jet, viridis, plasma, inferno, - magma, parula, nipy_spectral, RdBu, bwr - :kword title: string to use as plot title instead of time. - Special case: Set to "msec" to plot time with millisecond accuracy or "musec" - for microsecond accuracy. "sec" is integer second accuracy. - :kword cbtitle: string to use as colorbar title instead of map name - :kword axisunit: Plot axes using 10^{axisunit} m (default: Earth radius R_E) - :kword tickinterval: Interval at which to have ticks on axes (not colorbar) - - :kwird usesci: Use scientific notation for colorbar ticks? (default: True) - :kword vmin,vmax: min and max values for colour scale and colour bar. If no values are given, - min and max values for whole plot (non-zero rho regions only) are used. - :kword symmetric: Set the absolute value of vmin and vmax to the greater of the two - :kword lin: Flag for using linear colour scaling instead of log - :kword symlog: Use logarithmic scaling, but linear when abs(value) is below the value given to symlog. - Allows symmetric quasi-logarithmic plots of e.g. transverse field components. - A given of 0 translates to a threshold of max(abs(vmin),abs(vmax)) * 1.e-2, but this can - result in the innermost tick marks overlapping. In this case, using a larger value for - symlog is suggested. - :kword wmark: If set to non-zero, will plot a Vlasiator watermark in the top left corner. If set to a text - string, tries to use that as the location, e.g. "NW","NE","SW","SW" - :kword wmarkb: As for wmark, but uses an all-black Vlasiator logo. - :kword Earth: If set, draws an earth at (0,0) - :kword highres: Creates the image in high resolution, scaled up by this value (suitable for print). - - - :kword draw: Set to nonzero in order to draw image on-screen instead of saving to file (requires x-windowing) - - :kword noborder: Plot figure edge-to-edge without borders (default off) - :kword noxlabels: Suppress x-axis labels and title - :kword noylabels: Suppress y-axis labels and title - :kword scale: Scale text size (default=1.0) - :kword thick: line and axis thickness, default=1.0 - :kword nocb: Set to suppress drawing of colourbar - :kword internalcb: Set to draw colorbar inside plot instead of outside. If set to a text - string, tries to use that as the location, e.g. "NW","NE","SW","SW" - - :kword external: Optional function to use for external plotting of e.g. contours. The function - receives the following arguments: ax, XmeshXY,YmeshXY, pass_maps - If the function accepts a fifth variable, if set to true, it is expected to - return a list of required variables for constructing the pass_maps dictionary. - :kword expression: Optional function which calculates a custom expression to plot. The function - receives the same dictionary of numpy arrays as external, as an argument pass_maps, - the contents of which are maps of variables. Each is either of size [ysize,xsize] - or for multi-dimensional variables (vectors, tensors) it's [ysize,xsize,dim]. - If the function accepts a second variable, if set to true, it is expected to - return a list of required variables for pass_maps. - - Important note: the dictionaries of arrays passed to external and expression are of shape [ysize,xzize], so - for some analysis transposing them is necessary. For pre-existing functions to use and to base new functions - on, see the plot_helpers.py file. - - :kword vscale: Scale all values with this before plotting. Useful for going from e.g. m^-3 to cm^-3 - or from tesla to nanotesla. Guesses correct units for colourbar for some known - variables. Set to None to seek for a default scaling. - :kword absolute: Plot the absolute of the evaluated variable - - :kword pass_vars: Optional list of map names to pass to the external/expression functions - as a dictionary of numpy arrays. Each is either of size [ysize,xsize] or - for multi-dimensional variables (vectors, tensors) it's [ysize,xsize,dim]. - :kword pass_times: Integer, how many timesteps in each direction should be passed to external/expression - functions in pass_vars (e.g. pass_times=1 passes the values of three timesteps). If - pass_times has two values, the first is the extent before, the second after. - (e.g. pass_times=[2,1] passes the values of two preceding and one following timesteps - for a total of four timesteps) - This causes pass_vars to become a list of timesteps, with each timestep containing - a dictionary of numpy arrays as for regular pass_vars. An additional dictionary entry is - added as 'dstep' which gives the timestep offset from the master frame. - Does not work if working from a vlsv-object. - :kword pass_full: Set to anything but None in order to pass the full arrays instead of a zoomed-in section - - :kword diff: Instead of a regular plot, plot the difference between the selected plot type for - the regular source file and the file given by this keyword. This overides external - and expression keywords, as well as related pass_vars, pass_times, and pass_full. - - :kword fsaved: Overplot locations of fSaved. If keyword is set to a string, that will be the colour used. - :kword nomask: Do not mask plotting based on proton density - - :kword vectors: Set to a vector variable to overplot (unit length vectors, color displays variable magnitude) - :kword vectordensity: Aim for how many vectors to show in plot window (default 100) - :kword vectorcolormap: Colormap to use for overplotted vectors (default: gray) - :kword vectorsize: Scaling of vector sizes - - :kword streamlines: Set to a vector variable to overplot as streamlines - :kword streamlinedensity: Set streamline density (default 1) - :kword streamlinecolor: Set streamline color (default white) - :kword streamlinethick: Set streamline thickness - - :kword axes: Provide the routine a set of axes to draw within instead of generating a new image. - It is recommended to either also provide cbaxes or activate nocb, unless one wants a colorbar - to be automatically added next to the panel (but this may affect the overall layout) - Note that the aspect ratio of the colormap is made equal in any case, hence the axes - proportions may change if the box and axes size are not designed to match by the user - :kword cbaxes: Provide the routine a set of axes for the colourbar. - :kword normal: Direction of the normal of the 2D cut through ('x', 'y', or 'z' or a vector) - :kword cutpoint: Coordinate (in normal direction) through which the cut must pass [m] - :kword cutpointre: Coordinate (in normal direction) through which the cut must pass [rE] - :kword useimshow: Use imshow for raster background instead (default: False) - :kword imshowinterp: Use this matplotlib interpolation for imshow (default: 'none') - - - :returns: Outputs an image to a file or to the screen. - - .. code-block:: python - - # Example usage: - plot_colormap(filename=fileLocation, var="MA", run="BCQ", - colormap='nipy_spectral',step=j, outputdir=outputLocation, - lin=1, wmark=1, vmin=2.7, vmax=10, - external=cavitoncontours, pass_vars=['rho','B','beta']) - # Where cavitoncontours is an external function which receives the arguments - # ax, XmeshXY,YmeshXY, pass_maps - # where pass_maps is a dictionary of maps for the requested variables. - - # example (simple) use of expressions: - def exprMA_cust(exprmaps, requestvariables=False): - if requestvariables==True: - return ['va'] - custombulkspeed=750000. # m/s - va = exprmaps['va'][:,:] - MA = custombulkspeed/va - return MA - plot_colormap(filename=fileLocation, vmin=1 vmax=40, expression=exprMA_cust,lin=1) + :kword filename: path to .vlsv file to use for input. Assumes a bulk file. + :kword vlsvobj: Optionally provide a python vlsvfile object instead + :kword filedir: Optionally provide directory where files are located and use step for bulk file name + :kword step: output step index, used for constructing output (and possibly input) filename + :kword run: run identifier, used for constructing output filename + :kword outputdir: path to directory where output files are created (default: $HOME/Plots/ or override with PTOUTPUTDIR) + If directory does not exist, it will be created. If the string does not end in a + forward slash, the final part will be used as a prefix for the files. + :kword outputfile: Singular output file name + + :kword nooverwrite: Set to only perform actions if the target output file does not yet exist + + :kword var: variable to plot, e.g. rho, RhoBackstream, beta, Temperature, MA, Mms, va, vms, + E, B, v, V or others. Accepts any variable known by analysator/pytools. + Per-population variables are simply given as "proton/rho" etc + :kword operator: Operator to apply to variable: None, x, y, or z. Vector variables return either + the queried component, or otherwise the magnitude. + :kword op: duplicate of operator + + :kword boxm: zoom box extents [x0,x1,y0,y1] in metres (default and truncate to: whole simulation box) + :kword boxre: zoom box extents [x0,x1,y0,y1] in Earth radii (default and truncate to: whole simulation box) + :kword colormap: colour scale for plot, use e.g. hot_desaturated, jet, viridis, plasma, inferno, + magma, parula, nipy_spectral, RdBu, bwr + :kword title: string to use as plot title instead of time. + Special case: Set to "msec" to plot time with millisecond accuracy or "musec" + for microsecond accuracy. "sec" is integer second accuracy. + :kword cbtitle: string to use as colorbar title instead of map name + :kword axisunit: Plot axes using 10^{axisunit} m (default: Earth radius R_E) + :kword tickinterval: Interval at which to have ticks on axes (not colorbar) + + :kwird usesci: Use scientific notation for colorbar ticks? (default: True) + :kword vmin,vmax: min and max values for colour scale and colour bar. If no values are given, + min and max values for whole plot (non-zero rho regions only) are used. + :kword symmetric: Set the absolute value of vmin and vmax to the greater of the two + :kword lin: Flag for using linear colour scaling instead of log + :kword symlog: Use logarithmic scaling, but linear when abs(value) is below the value given to symlog. + Allows symmetric quasi-logarithmic plots of e.g. transverse field components. + A given of 0 translates to a threshold of max(abs(vmin),abs(vmax)) * 1.e-2, but this can + result in the innermost tick marks overlapping. In this case, using a larger value for + symlog is suggested. + :kword wmark: If set to non-zero, will plot a Vlasiator watermark in the top left corner. If set to a text + string, tries to use that as the location, e.g. "NW","NE","SW","SW" + :kword wmarkb: As for wmark, but uses an all-black Vlasiator logo. + :kword Earth: If set, draws an earth at (0,0) + :kword highres: Creates the image in high resolution, scaled up by this value (suitable for print). + + + :kword draw: Set to nonzero in order to draw image on-screen instead of saving to file (requires x-windowing) + + :kword noborder: Plot figure edge-to-edge without borders (default off) + :kword noxlabels: Suppress x-axis labels and title + :kword noylabels: Suppress y-axis labels and title + :kword scale: Scale text size (default=1.0) + :kword thick: line and axis thickness, default=1.0 + :kword nocb: Set to suppress drawing of colourbar + :kword internalcb: Set to draw colorbar inside plot instead of outside. If set to a text + string, tries to use that as the location, e.g. "NW","NE","SW","SW" + + :kword external: Optional function to use for external plotting of e.g. contours. The function + receives the following arguments: ax, XmeshXY,YmeshXY, pass_maps + If the function accepts a fifth variable, if set to true, it is expected to + return a list of required variables for constructing the pass_maps dictionary. + :kword expression: Optional function which calculates a custom expression to plot. The function + receives the same dictionary of numpy arrays as external, as an argument pass_maps, + the contents of which are maps of variables. Each is either of size [ysize,xsize] + or for multi-dimensional variables (vectors, tensors) it's [ysize,xsize,dim]. + If the function accepts a second variable, if set to true, it is expected to + return a list of required variables for pass_maps. + + Important note: the dictionaries of arrays passed to external and expression are of shape [ysize,xzize], so + for some analysis transposing them is necessary. For pre-existing functions to use and to base new functions + on, see the plot_helpers.py file. + + :kword vscale: Scale all values with this before plotting. Useful for going from e.g. m^-3 to cm^-3 + or from tesla to nanotesla. Guesses correct units for colourbar for some known + variables. Set to None to seek for a default scaling. + :kword absolute: Plot the absolute of the evaluated variable + + :kword pass_vars: Optional list of map names to pass to the external/expression functions + as a dictionary of numpy arrays. Each is either of size [ysize,xsize] or + for multi-dimensional variables (vectors, tensors) it's [ysize,xsize,dim]. + :kword pass_times: Integer, how many timesteps in each direction should be passed to external/expression + functions in pass_vars (e.g. pass_times=1 passes the values of three timesteps). If + pass_times has two values, the first is the extent before, the second after. + (e.g. pass_times=[2,1] passes the values of two preceding and one following timesteps + for a total of four timesteps) + This causes pass_vars to become a list of timesteps, with each timestep containing + a dictionary of numpy arrays as for regular pass_vars. An additional dictionary entry is + added as 'dstep' which gives the timestep offset from the master frame. + Does not work if working from a vlsv-object. + :kword pass_full: Set to anything but None in order to pass the full arrays instead of a zoomed-in section + + :kword diff: Instead of a regular plot, plot the difference between the selected plot type for + the regular source file and the file given by this keyword. This overides external + and expression keywords, as well as related pass_vars, pass_times, and pass_full. + + :kword fsaved: Overplot locations of fSaved. If keyword is set to a string, that will be the colour used. + :kword nomask: Do not mask plotting based on proton density + + :kword vectors: Set to a vector variable to overplot (unit length vectors, color displays variable magnitude) + :kword vectordensity: Aim for how many vectors to show in plot window (default 100) + :kword vectorcolormap: Colormap to use for overplotted vectors (default: gray) + :kword vectorsize: Scaling of vector sizes + + :kword streamlines: Set to a vector variable to overplot as streamlines + :kword streamlinedensity: Set streamline density (default 1) + :kword streamlinecolor: Set streamline color (default white) + :kword streamlinethick: Set streamline thickness + + :kword axes: Provide the routine a set of axes to draw within instead of generating a new image. + It is recommended to either also provide cbaxes or activate nocb, unless one wants a colorbar + to be automatically added next to the panel (but this may affect the overall layout) + Note that the aspect ratio of the colormap is made equal in any case, hence the axes + proportions may change if the box and axes size are not designed to match by the user + :kword cbaxes: Provide the routine a set of axes for the colourbar. + :kword normal: Direction of the normal of the 2D cut through ('x', 'y', or 'z' or a vector) + :kword cutpoint: Coordinate (in normal direction) through which the cut must pass [m] + :kword cutpointre: Coordinate (in normal direction) through which the cut must pass [rE] + :kword useimshow: Use imshow for raster background instead (default: False) + :kword imshowinterp: Use this matplotlib interpolation for imshow (default: 'none') + + + :returns: Outputs an image to a file or to the screen. + + .. code-block:: python + + # Example usage: + plot_colormap(filename=fileLocation, var="MA", run="BCQ", + colormap='nipy_spectral',step=j, outputdir=outputLocation, + lin=1, wmark=1, vmin=2.7, vmax=10, + external=cavitoncontours, pass_vars=['rho','B','beta']) + # Where cavitoncontours is an external function which receives the arguments + # ax, XmeshXY,YmeshXY, pass_maps + # where pass_maps is a dictionary of maps for the requested variables. + + # example (simple) use of expressions: + def exprMA_cust(exprmaps, requestvariables=False): + if requestvariables==True: + return ['va'] + custombulkspeed=750000. # m/s + va = exprmaps['va'][:,:] + MA = custombulkspeed/va + return MA + plot_colormap(filename=fileLocation, vmin=1 vmax=40, expression=exprMA_cust,lin=1) ''' diff --git a/pyPlots/plot_isosurface.py b/pyPlots/plot_isosurface.py index 29c2a013..eaea3e32 100644 --- a/pyPlots/plot_isosurface.py +++ b/pyPlots/plot_isosurface.py @@ -824,153 +824,153 @@ def plot_neutral_sheet(filename=None, ''' Plots a coloured plot along the neutral sheet with axes and a colour bar. - :kword filename: path to .vlsv file to use for input. Assumes a bulk file. - :kword vlsvobj: Optionally provide a python vlsvfile object instead - :kword filedir: Optionally provide directory where files are located and use step for bulk file name - :kword step: output step index, used for constructing output (and possibly input) filename - :kword run: run identifier, used for constructing output filename - :kword outputdir: path to directory where output files are created (default: $HOME/Plots/ or override with PTOUTPUTDIR) - If directory does not exist, it will be created. If the string does not end in a - forward slash, the final part will be used as a prefix for the files. - :kword outputfile: Singular output file name - - :kword nooverwrite: Set to only perform actions if the target output file does not yet exist - - :kword var: variable to plot, e.g. rho, RhoBackstream, beta, Temperature, MA, Mms, va, vms, - E, B, v, V or others. Accepts any variable known by analysator/pytools. - Per-population variables are simply given as "proton/rho" etc - :kword operator: Operator to apply to variable: None, x, y, or z. Vector variables return either - the queried component, or otherwise the magnitude. - :kword op: duplicate of operator - - :kword boxm: zoom box extents [x0,x1,y0,y1] in metres (default and truncate to: whole simulation box) - :kword boxre: zoom box extents [x0,x1,y0,y1] in Earth radii (default and truncate to: whole simulation box) - :kword colormap: colour scale for plot, use e.g. hot_desaturated, jet, viridis, plasma, inferno, - magma, parula, nipy_spectral, RdBu, bwr - :kword title: string to use as plot title instead of time. - Special case: Set to "msec" to plot time with millisecond accuracy or "musec" - for microsecond accuracy. "sec" is integer second accuracy. - :kword cbtitle: string to use as colorbar title instead of map name - :kword axisunit: Plot axes using 10^{axisunit} m (default: Earth radius R_E) - :kword tickinterval: Interval at which to have ticks on axes (not colorbar) - - :kwird usesci: Use scientific notation for colorbar ticks? (default: True) - :kword vmin,vmax: min and max values for colour scale and colour bar. If no values are given, - min and max values for whole plot (non-zero rho regions only) are used. - :kword symmetric: Set the absolute value of vmin and vmax to the greater of the two - :kword lin: Flag for using linear colour scaling instead of log - :kword symlog: Use logarithmic scaling, but linear when abs(value) is below the value given to symlog. - Allows symmetric quasi-logarithmic plots of e.g. transverse field components. - A given of 0 translates to a threshold of max(abs(vmin),abs(vmax)) * 1.e-2, but this can - result in the innermost tick marks overlapping. In this case, using a larger value for - symlog is suggested. - :kword wmark: If set to non-zero, will plot a Vlasiator watermark in the top left corner. If set to a text - string, tries to use that as the location, e.g. "NW","NE","SW","SW" - :kword wmarkb: As for wmark, but uses an all-black Vlasiator logo. - :kword Earth: If set, draws an earth at (0,0) - :kword highres: Creates the image in high resolution, scaled up by this value (suitable for print). - - - :kword draw: Set to nonzero in order to draw image on-screen instead of saving to file (requires x-windowing) - - :kword noborder: Plot figure edge-to-edge without borders (default off) - :kword noxlabels: Suppress x-axis labels and title - :kword noylabels: Suppress y-axis labels and title - :kword scale: Scale text size (default=1.0) - :kword thick: line and axis thickness, default=1.0 - :kword nocb: Set to suppress drawing of colourbar - :kword internalcb: Set to draw colorbar inside plot instead of outside. If set to a text - string, tries to use that as the location, e.g. "NW","NE","SW","SW" - - :kword external: Optional function to use for external plotting of e.g. contours. The function - receives the following arguments: ax, XmeshXY,YmeshXY, pass_maps - If the function accepts a fifth variable, if set to true, it is expected to - return a list of required variables for constructing the pass_maps dictionary. - :kword expression: Optional function which calculates a custom expression to plot. The function - receives the same dictionary of numpy arrays as external, as an argument pass_maps, - the contents of which are maps of variables. Each is either of size [ysize,xsize] - or for multi-dimensional variables (vectors, tensors) it's [ysize,xsize,dim]. - If the function accepts a second variable, if set to true, it is expected to - return a list of required variables for pass_maps. - - Important note: the dictionaries of arrays passed to external and expression are of shape [ysize,xzize], so - for some analysis transposing them is necessary. For pre-existing functions to use and to base new functions - on, see the plot_helpers.py file. - - :kword vscale: Scale all values with this before plotting. Useful for going from e.g. m^-3 to cm^-3 - or from tesla to nanotesla. Guesses correct units for colourbar for some known - variables. Set to None to seek for a default scaling. - :kword absolute: Plot the absolute of the evaluated variable - - :kword pass_vars: Optional list of map names to pass to the external/expression functions - as a dictionary of numpy arrays. Each is either of size [ysize,xsize] or - for multi-dimensional variables (vectors, tensors) it's [ysize,xsize,dim]. - :kword pass_times: Integer, how many timesteps in each direction should be passed to external/expression - functions in pass_vars (e.g. pass_times=1 passes the values of three timesteps). If - pass_times has two values, the first is the extent before, the second after. - (e.g. pass_times=[2,1] passes the values of two preceding and one following timesteps - for a total of four timesteps) - This causes pass_vars to become a list of timesteps, with each timestep containing - a dictionary of numpy arrays as for regular pass_vars. An additional dictionary entry is - added as 'dstep' which gives the timestep offset from the master frame. - Does not work if working from a vlsv-object. - :kword pass_full: Set to anything but None in order to pass the full arrays instead of a zoomed-in section - - :kword diff: Instead of a regular plot, plot the difference between the selected plot type for - the regular source file and the file given by this keyword. This overides external - and expression keywords, as well as related pass_vars, pass_times, and pass_full. - - :kword z_extent: Search bracket for the neutral sheet in axisunit units - :kword folding_alpha: If non-zero, plots transparent dots over the regions where the sheet has multiple separate z-values. A value of 1.0 is opaque, a value of 0.0 is transparent. - :kword sheetlayer: If set to 'above', plots the topmost layer of the neutral sheet in case of folding. If set to anything else, - the downmost layer is plotted. - :kword nomask: Do not mask plotting based on proton density - - :kword vectors: Set to a vector variable to overplot (unit length vectors, color displays variable magnitude) - :kword vectordensity: Aim for how many vectors to show in plot window (default 100) - :kword vectorcolormap: Colormap to use for overplotted vectors (default: gray) - :kword vectorsize: Scaling of vector sizes - - :kword streamlines: Set to a vector variable to overplot as streamlines - :kword streamlinedensity: Set streamline density (default 1) - :kword streamlinecolor: Set streamline color (default white) - :kword streamlinethick: Set streamline thickness - - :kword axes: Provide the routine a set of axes to draw within instead of generating a new image. - It is recommended to either also provide cbaxes or activate nocb, unless one wants a colorbar - to be automatically added next to the panel (but this may affect the overall layout) - Note that the aspect ratio of the colormap is made equal in any case, hence the axes - proportions may change if the box and axes size are not designed to match by the user - :kword cbaxes: Provide the routine a set of axes for the colourbar. - :kword normal: Direction of the normal of the 2D cut through ('x', 'y', or 'z' or a vector) - :kword cutpoint: Coordinate (in normal direction) through which the cut must pass [m] - :kword cutpointre: Coordinate (in normal direction) through which the cut must pass [rE] - :kword useimshow: Use imshow for raster background instead (default: False) - :kword imshowinterp: Use this matplotlib interpolation for imshow (default: 'none') - - - :returns: Outputs an image to a file or to the screen. - - .. code-block:: python - - # Example usage: - plot_colormap(filename=fileLocation, var="MA", run="BCQ", - colormap='nipy_spectral',step=j, outputdir=outputLocation, - lin=1, wmark=1, vmin=2.7, vmax=10, - external=cavitoncontours, pass_vars=['rho','B','beta']) - # Where cavitoncontours is an external function which receives the arguments - # ax, XmeshXY,YmeshXY, pass_maps - # where pass_maps is a dictionary of maps for the requested variables. - - # example (simple) use of expressions: - def exprMA_cust(exprmaps, requestvariables=False): - if requestvariables==True: - return ['va'] - custombulkspeed=750000. # m/s - va = exprmaps['va'][:,:] - MA = custombulkspeed/va - return MA - plot_colormap(filename=fileLocation, vmin=1 vmax=40, expression=exprMA_cust,lin=1) + :kword filename: path to .vlsv file to use for input. Assumes a bulk file. + :kword vlsvobj: Optionally provide a python vlsvfile object instead + :kword filedir: Optionally provide directory where files are located and use step for bulk file name + :kword step: output step index, used for constructing output (and possibly input) filename + :kword run: run identifier, used for constructing output filename + :kword outputdir: path to directory where output files are created (default: $HOME/Plots/ or override with PTOUTPUTDIR) + If directory does not exist, it will be created. If the string does not end in a + forward slash, the final part will be used as a prefix for the files. + :kword outputfile: Singular output file name + + :kword nooverwrite: Set to only perform actions if the target output file does not yet exist + + :kword var: variable to plot, e.g. rho, RhoBackstream, beta, Temperature, MA, Mms, va, vms, + E, B, v, V or others. Accepts any variable known by analysator/pytools. + Per-population variables are simply given as "proton/rho" etc + :kword operator: Operator to apply to variable: None, x, y, or z. Vector variables return either + the queried component, or otherwise the magnitude. + :kword op: duplicate of operator + + :kword boxm: zoom box extents [x0,x1,y0,y1] in metres (default and truncate to: whole simulation box) + :kword boxre: zoom box extents [x0,x1,y0,y1] in Earth radii (default and truncate to: whole simulation box) + :kword colormap: colour scale for plot, use e.g. hot_desaturated, jet, viridis, plasma, inferno, + magma, parula, nipy_spectral, RdBu, bwr + :kword title: string to use as plot title instead of time. + Special case: Set to "msec" to plot time with millisecond accuracy or "musec" + for microsecond accuracy. "sec" is integer second accuracy. + :kword cbtitle: string to use as colorbar title instead of map name + :kword axisunit: Plot axes using 10^{axisunit} m (default: Earth radius R_E) + :kword tickinterval: Interval at which to have ticks on axes (not colorbar) + + :kwird usesci: Use scientific notation for colorbar ticks? (default: True) + :kword vmin,vmax: min and max values for colour scale and colour bar. If no values are given, + min and max values for whole plot (non-zero rho regions only) are used. + :kword symmetric: Set the absolute value of vmin and vmax to the greater of the two + :kword lin: Flag for using linear colour scaling instead of log + :kword symlog: Use logarithmic scaling, but linear when abs(value) is below the value given to symlog. + Allows symmetric quasi-logarithmic plots of e.g. transverse field components. + A given of 0 translates to a threshold of max(abs(vmin),abs(vmax)) * 1.e-2, but this can + result in the innermost tick marks overlapping. In this case, using a larger value for + symlog is suggested. + :kword wmark: If set to non-zero, will plot a Vlasiator watermark in the top left corner. If set to a text + string, tries to use that as the location, e.g. "NW","NE","SW","SW" + :kword wmarkb: As for wmark, but uses an all-black Vlasiator logo. + :kword Earth: If set, draws an earth at (0,0) + :kword highres: Creates the image in high resolution, scaled up by this value (suitable for print). + + + :kword draw: Set to nonzero in order to draw image on-screen instead of saving to file (requires x-windowing) + + :kword noborder: Plot figure edge-to-edge without borders (default off) + :kword noxlabels: Suppress x-axis labels and title + :kword noylabels: Suppress y-axis labels and title + :kword scale: Scale text size (default=1.0) + :kword thick: line and axis thickness, default=1.0 + :kword nocb: Set to suppress drawing of colourbar + :kword internalcb: Set to draw colorbar inside plot instead of outside. If set to a text + string, tries to use that as the location, e.g. "NW","NE","SW","SW" + + :kword external: Optional function to use for external plotting of e.g. contours. The function + receives the following arguments: ax, XmeshXY,YmeshXY, pass_maps + If the function accepts a fifth variable, if set to true, it is expected to + return a list of required variables for constructing the pass_maps dictionary. + :kword expression: Optional function which calculates a custom expression to plot. The function + receives the same dictionary of numpy arrays as external, as an argument pass_maps, + the contents of which are maps of variables. Each is either of size [ysize,xsize] + or for multi-dimensional variables (vectors, tensors) it's [ysize,xsize,dim]. + If the function accepts a second variable, if set to true, it is expected to + return a list of required variables for pass_maps. + + Important note: the dictionaries of arrays passed to external and expression are of shape [ysize,xzize], so + for some analysis transposing them is necessary. For pre-existing functions to use and to base new functions + on, see the plot_helpers.py file. + + :kword vscale: Scale all values with this before plotting. Useful for going from e.g. m^-3 to cm^-3 + or from tesla to nanotesla. Guesses correct units for colourbar for some known + variables. Set to None to seek for a default scaling. + :kword absolute: Plot the absolute of the evaluated variable + + :kword pass_vars: Optional list of map names to pass to the external/expression functions + as a dictionary of numpy arrays. Each is either of size [ysize,xsize] or + for multi-dimensional variables (vectors, tensors) it's [ysize,xsize,dim]. + :kword pass_times: Integer, how many timesteps in each direction should be passed to external/expression + functions in pass_vars (e.g. pass_times=1 passes the values of three timesteps). If + pass_times has two values, the first is the extent before, the second after. + (e.g. pass_times=[2,1] passes the values of two preceding and one following timesteps + for a total of four timesteps) + This causes pass_vars to become a list of timesteps, with each timestep containing + a dictionary of numpy arrays as for regular pass_vars. An additional dictionary entry is + added as 'dstep' which gives the timestep offset from the master frame. + Does not work if working from a vlsv-object. + :kword pass_full: Set to anything but None in order to pass the full arrays instead of a zoomed-in section + + :kword diff: Instead of a regular plot, plot the difference between the selected plot type for + the regular source file and the file given by this keyword. This overides external + and expression keywords, as well as related pass_vars, pass_times, and pass_full. + + :kword z_extent: Search bracket for the neutral sheet in axisunit units + :kword folding_alpha: If non-zero, plots transparent dots over the regions where the sheet has multiple separate z-values. A value of 1.0 is opaque, a value of 0.0 is transparent. + :kword sheetlayer: If set to 'above', plots the topmost layer of the neutral sheet in case of folding. If set to anything else, + the downmost layer is plotted. + :kword nomask: Do not mask plotting based on proton density + + :kword vectors: Set to a vector variable to overplot (unit length vectors, color displays variable magnitude) + :kword vectordensity: Aim for how many vectors to show in plot window (default 100) + :kword vectorcolormap: Colormap to use for overplotted vectors (default: gray) + :kword vectorsize: Scaling of vector sizes + + :kword streamlines: Set to a vector variable to overplot as streamlines + :kword streamlinedensity: Set streamline density (default 1) + :kword streamlinecolor: Set streamline color (default white) + :kword streamlinethick: Set streamline thickness + + :kword axes: Provide the routine a set of axes to draw within instead of generating a new image. + It is recommended to either also provide cbaxes or activate nocb, unless one wants a colorbar + to be automatically added next to the panel (but this may affect the overall layout) + Note that the aspect ratio of the colormap is made equal in any case, hence the axes + proportions may change if the box and axes size are not designed to match by the user + :kword cbaxes: Provide the routine a set of axes for the colourbar. + :kword normal: Direction of the normal of the 2D cut through ('x', 'y', or 'z' or a vector) + :kword cutpoint: Coordinate (in normal direction) through which the cut must pass [m] + :kword cutpointre: Coordinate (in normal direction) through which the cut must pass [rE] + :kword useimshow: Use imshow for raster background instead (default: False) + :kword imshowinterp: Use this matplotlib interpolation for imshow (default: 'none') + + + :returns: Outputs an image to a file or to the screen. + + .. code-block:: python + + # Example usage: + plot_colormap(filename=fileLocation, var="MA", run="BCQ", + colormap='nipy_spectral',step=j, outputdir=outputLocation, + lin=1, wmark=1, vmin=2.7, vmax=10, + external=cavitoncontours, pass_vars=['rho','B','beta']) + # Where cavitoncontours is an external function which receives the arguments + # ax, XmeshXY,YmeshXY, pass_maps + # where pass_maps is a dictionary of maps for the requested variables. + + # example (simple) use of expressions: + def exprMA_cust(exprmaps, requestvariables=False): + if requestvariables==True: + return ['va'] + custombulkspeed=750000. # m/s + va = exprmaps['va'][:,:] + MA = custombulkspeed/va + return MA + plot_colormap(filename=fileLocation, vmin=1 vmax=40, expression=exprMA_cust,lin=1) ''' diff --git a/pyVlsv/vlsvreader.py b/pyVlsv/vlsvreader.py index dd2b6784..559148fc 100644 --- a/pyVlsv/vlsvreader.py +++ b/pyVlsv/vlsvreader.py @@ -748,6 +748,7 @@ def get_all_variables( self ): ''' Returns all variables in the vlsv reader and the data reducer :returns: List of variable is in the vlsv file .. code-block:: python + # Example usage: vlsvReader = pt.vlsvfile.VlsvReader("test.vlsv") vars = vlsvReader.get_variables() @@ -842,8 +843,10 @@ def get_config(self): EXAMPLE: if the config contains these lines: + [proton_precipitation] nChannels = 9 + then the following returns ['9']: vlsvReader.get_config()['proton_precipitation']['nChannels'] ''' @@ -1553,12 +1556,20 @@ def read_interpolated_variable_irregular(self, name, coords, operator="pass",per }): ''' Read a linearly interpolated variable value from the open vlsv file. Arguments: + :param name: Name of the variable + :param coords: Coordinates from which to read data + :param periodic: Periodicity of the system. Default is periodic in all dimension + :param operator: Datareduction operator. "pass" does no operation on data + + :param method: Method for interpolation, default "linear" ("nearest", "rbf, "delaunay") + :param methodargs: Dict of dicts to pass kwargs to interpolators. Default values for "rbf", "delaunay"; + see scipy.interpolate.RBFInterpolator for rbf and scipy.interpolate.LinearNDInterpolator for delaunay :returns: numpy array with the data @@ -2193,7 +2204,9 @@ def get_fsgrid_coordinates(self, ri): def get_unique_cellids(self, coords): ''' Returns a list of cellids containing all the coordinates in coords, with no duplicate cellids. Relative order of elements is conserved. + :param coords: A list of coordinates + :returns: a list of unique cell ids ''' # cids = [int(self.get_cellid(coord)) for coord in coords] @@ -2468,9 +2481,10 @@ def get_dual(self, pts, cellids=None): # For now, combined caching accessor and builder def build_cell_vertices(self, cid, prune_unique=False): ''' Builds, caches and returns the vertices that lie on the surfaces of CellIDs cid. + :parameter cid: numpy array of CellIDs :parameter prune_unique: bool [False], if you suspect you might be calling the function many times with the - same CellID in the list, it might be beneficial to enable this and not repeat the operation for duplicate entries. + same CellID in the list, it might be beneficial to enable this and not repeat the operation for duplicate entries. :returns: Dictionary of cell c (int) : set of vertex indices (3-tuple) that touch the cell c. diff --git a/pyVlsv/vlsvwriter.py b/pyVlsv/vlsvwriter.py index a789a924..6940f71f 100644 --- a/pyVlsv/vlsvwriter.py +++ b/pyVlsv/vlsvwriter.py @@ -362,6 +362,7 @@ def __write(self, data, name, tag, mesh, extra_attribs={}): def write_variable_info(self, varinfo, mesh, unitConversion, extra_attribs={}): ''' Writes an array into the vlsv file as a variable; requires input of metadata required by VlsvReader + :param varinfo: VariableInfo object containing -data: The variable data (array) -name: Name of the data array diff --git a/scripts/biot_savart.py b/scripts/biot_savart.py index beacc20a..e2f74150 100644 --- a/scripts/biot_savart.py +++ b/scripts/biot_savart.py @@ -1,11 +1,11 @@ ''' - Follow Welling et al. (2020) calculate the magnetic field at Earth's surface. + Follow Welling et al. (2020) calculate the magnetic field at Earth's surface. Integrate Biot-Savart over: - 1. All currents within the Vlasov domain - 2. Birkeland currents (FACs) in the “gap region” between the MHD inner boundary and the ionosphere, - mapped (assuming J \propto B) along the field lines connecting ionosphere radius R_IONO to coupling radius r_C - 3. Horizontal Ionospheric currents (altitude 100 km) + + 1. All currents within the Vlasov domain + 2. Birkeland currents (FACs) in the “gap region” between the MHD inner boundary and the ionosphere, mapped (assuming J \\propto B) along the field lines connecting ionosphere radius R_IONO to coupling radius r_C + 3. Horizontal Ionospheric currents (altitude 100 km) The integration is a discrete summation over the 3 domains. @@ -46,13 +46,9 @@ # Input parameters import argparse -parser = argparse.ArgumentParser() - -parser.add_argument('-run', default='FHA', help="run name" ) -parser.add_argument('-task', default=0, help="task no." ) -parser.add_argument('-nproc', default=1, help="number of processors to use " ) + global ARGS -ARGS = parser.parse_args() + def mkdir_path(path): @@ -122,6 +118,7 @@ def b_dip_direction(x, y, z, mag_mom_vector = np.array([0., 0., -8e22])): ''' Inputs: cartesian coordinates x,y,z [m] keyword mag_mom_vector: Earth's vector magnetic dipole moment + Outputs: dipole magnetic field unit vector ''' B = b_dip(x, y, z, mag_mom_vector = mag_mom_vector) @@ -131,6 +128,7 @@ def b_dip(x, y, z, mag_mom_vector = np.array([0., 0., -8e22])): ''' Inputs: cartesian coordinates x,y,z [m] keyword mag_mom_vector: Earth's vector magnetic dipole moment + Outputs: dipole magnetic field ''' N = x.size @@ -226,21 +224,25 @@ def nearest_node_index(f, x, y, z, node_coords_iono = None): def fac_map(f, vg_x, vg_y, vg_z, dx, f_J_sidecar = None, r_C = 5 * 6.371e6, mag_mom_vector = np.array([0., 0., -8e22])): ''' - Map the FACs along magnetic field lines (J \propto B). + Map the FACs along magnetic field lines (J \\propto B). Inputs: f: VlsvReader object f_J_sidecar: vlsvReader object that contains pre-computed current 'vg_J' - if f_J_sidecar = None: + + ``if f_J_sidecar = None:`` here is assumed the data reducer 'ig_fac' exists (such as for runs FHA and FIA) - In this case, the currents in the FAC region (domain #2) will be mapped UP from the ionosphere 'ig_' grid - otherwise (f_J_sidecar = a *.vlsv string, for a file containing the current density J in the vlasov 'vg_' grid) - for run EGL, see files at /wrk-vakka/group/spacephysics/vlasiator/3D/EGL/visualizations_2/ballooning/*.vlsv - In this case, the currents in the FAC region (domain #2) will be mapped DOWN from the vg_ grid + In this case, the currents in the FAC region (domain #2) will be mapped UP from the ionosphere 'ig\\_' grid + otherwise (f_J_sidecar = a \\*.vlsv string, for a file containing the current density J in the vlasov 'vg\\_' grid) + for run EGL, see files at /wrk-vakka/group/spacephysics/vlasiator/3D/EGL/visualizations_2/ballooning/\\*.vlsv + In this case, the currents in the FAC region (domain #2) will be mapped DOWN from the vg\\_ grid + vg_x,vg_y,vg_z position [m], 1D numpy arrays. - note: these coordinates do not have to correspond with Vlasiator's vg_ grid, + note: these coordinates do not have to correspond with Vlasiator's vg\\_ grid, This is relevant when fac_map() is called by biot_savart(), with keyword mesh='refined' or mesh='graded' + dx is grid resolution [m], 1D numpy array, This is for the input cells which can be defined arbitrarily---not necessarily same as vg cells. + *** coordinates, not just coordinates on the vg_ grid *** Returns: @@ -304,9 +306,11 @@ def biot_savart(coord_list, f, f_J_sidecar = None, r_C = 5 * 6.371e6, mesh = 'gr ''' param coord_list: a list of 3-element arrays of coordinates [ [x1,y1,z1], [x2,y2,z2], ... ], SI units if considering just a single starting point, the code accepts a 3-element array-like object [x1,y1,z1] + f: vlsvReader object f_J_sidecar: vlsvReader object that contains pre-computed current 'vg_J' - e.g., for EGL, files at: /wrk-vakka/group/spacephysics/vlasiator/3D/EGL/visualizations_2/ballooning/*.vlsv + + e.g., for EGL, files at: /wrk-vakka/group/spacephysics/vlasiator/3D/EGL/visualizations_2/ballooning/\\*.vlsv runtime (FHA): overhead of about 200 sec (setup), plus 0.2 sec for each element of coord_list @@ -383,17 +387,20 @@ def integrate_biot_savart(coord_list, x, y, z, J, delta): ''' integration of the Biot-savart law magnetic field is evaluated at coordinates specified in coord_list (for example, the ionospheric coordinates) + Inputs: x,y,z (1D array, size n): Cartesian coordinates delta (1D array, size n): the volume or area of the element being integrated J (2D array, size [3, n]): current density + all units SI Outputs: magnetic field evaluated at coord_list Note: the units of J and delta depend on the type of integral (volume or surface), but the equation form is unchanged - Biot-Savart (volume): B = (mu_0 / 4 * pi) \int { J x r' / |r'|^3 } dV ([J] = A/m^2, delta == dV) - (surface): B = (mu_0 / 4 * pi) \int { J x r' / |r'|^3 } dA ([J] = A/m, delta = dS) + + Biot-Savart (volume): B = (mu_0 / 4 * pi) \\int { J x r' / \\|r'\\|^3 } dV ([J] = A/m^2, delta == dV) + (surface): B = (mu_0 / 4 * pi) \\int { J x r' / \\|r'\\|^3 } dA ([J] = A/m, delta = dS) ''' B = np.zeros((len(coord_list), 3)) r_p = np.zeros((3, x.size)) @@ -425,11 +432,17 @@ def B_ionosphere(f, coord_list = None, ig_r = None, method = 'integrate'): Inputs: f: VlsvReader object + keyword coord_list: locations where B-field is calculated + keyword ig_r: the ionospheric mesh + keyword method: + ='integrate' (default): integrate over the whole ionosphere using Biot-Savart law + ='local': ionosphere produces magnetic field locally, as by an infinite plane of current overhead + Outputs: Magnetic field evaluated at coord_list ''' @@ -479,6 +492,7 @@ def save_B_vlsv(input_tuple): ig_r: Cartesian ionospheric grid locations (radius R_EARTH + 100km) note that B_iono, B_inner, B_outer are in fact evaluated at radius R_EARTH ig_r is a copy of the Vlasiator ionosphere mesh, to enable combination with other data reducers + B_iono: Ionospheric (Domain #3) contribution to ground magnetic field (radius R_EARTH) B_inner: Ionospheric (Domain #2) contribution to ground magnetic field (radius R_EARTH) B_outer: Ionospheric (Domain #1) contribution to ground magnetic field (radius R_EARTH) @@ -542,6 +556,13 @@ def get_bulklocation(run): if __name__ == '__main__': + parser = argparse.ArgumentParser() + + parser.add_argument('-run', default='FHA', help="run name" ) + parser.add_argument('-task', default=0, help="task no." ) + parser.add_argument('-nproc', default=1, help="number of processors to use " ) + ARGS = parser.parse_args() + run = ARGS.run if run == 'EGL': first = 621 diff --git a/scripts/create_time_energy_spectrogram.py b/scripts/create_time_energy_spectrogram.py index bd7c9f69..99de51b6 100644 --- a/scripts/create_time_energy_spectrogram.py +++ b/scripts/create_time_energy_spectrogram.py @@ -20,51 +20,52 @@ # with this program; if not, write to the Free Software Foundation, Inc., # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. # +''' +Omnidirectional time-energy spectrogram +USAGE: python create_time_energy_spectrogram.py NCores vlsvFileNumberStart vlsvFileNumberEnd + NCores = number of multithreading cores + vlsvFileNumberStart = number of the first plotted VLSV file + vlsvFileNumberend = number of the last plotted VLSV file +The script assumes the following file name formats (Xs are integers): + VLSV files: bulk.XXXXXXX.vlsv (vlsvFolder) +ASCII output files: + energy spectra : outSpectraFilePrefix_bulk.XXXXXXX.vlsv.dat + bulk parameters: outBulkFilePrefix_bulk.XXXXXXX.vlsv.dat -# Omnidirectional time-energy spectrogram -# USAGE: python create_time_energy_spectrogram.py NCores vlsvFileNumberStart vlsvFileNumberEnd -# NCores = number of multithreading cores -# vlsvFileNumberStart = number of the first plotted VLSV file -# vlsvFileNumberend = number of the last plotted VLSV file -# The script assumes the following file name formats (Xs are integers): -# VLSV files: bulk.XXXXXXX.vlsv (vlsvFolder) -# ASCII output files: -# energy spectra : outSpectraFilePrefix_bulk.XXXXXXX.vlsv.dat -# bulk parameters: outBulkFilePrefix_bulk.XXXXXXX.vlsv.dat -# -# Energy spectra file format: -# CID1 CID2 CIDN -# Time Time ... -# NbinEdges Nbins ... -# EbinEdge1 EbinEdge1 ... -# EbinEdge2 EbinEdge2 ... -# ... ... ... -# EbinEdgeN EbinEdgeN ... -# Nbins Nbins ... -# bin1 bin1 ... -# bin2 bin2 ... -# ... ... ... -# binN binN ... -# where each column includes one spatial cell -# CIDX = cell id -# Time = simulation time -# NbinEdges = number of bin edges -# EbinEdgeX = energy value (in electron volts) of edge X -# Nbins = number of bins (should be NbinEdges - 1) -# binX = histogram value of energy bin X -# -# Bulk parameter file format: -# CID1 CID2 CIDN -# Time Time ... -# Param1 Param1 ... -# Param2 Param2 ... -# ... ... ... -# ParamN ParamN ... -# where each column includes one spatial cell -# CIDX = cell id -# Time = simulation time -# Param1...N = rho,rhovx,rhovy,rhovz,Bx,By,Bz,Ex,Ey,Ez,Pxx,Pyy,Pzz,POff1,POff2,POff3,T,Tpar,Tperp1,Tperp2,Tperp -# +Energy spectra file format: + CID1 CID2 CIDN + Time Time ... + NbinEdges Nbins ... + EbinEdge1 EbinEdge1 ... + EbinEdge2 EbinEdge2 ... + ... ... ... + EbinEdgeN EbinEdgeN ... + Nbins Nbins ... + bin1 bin1 ... + bin2 bin2 ... + ... ... ... + binN binN ... + where each column includes one spatial cell + CIDX = cell id + Time = simulation time + NbinEdges = number of bin edges + EbinEdgeX = energy value (in electron volts) of edge X + Nbins = number of bins (should be NbinEdges - 1) + binX = histogram value of energy bin X + +Bulk parameter file format: + CID1 CID2 CIDN + Time Time ... + Param1 Param1 ... + Param2 Param2 ... + ... ... ... + ParamN ParamN ... + where each column includes one spatial cell + CIDX = cell id + Time = simulation time + Param1...N = rho,rhovx,rhovy,rhovz,Bx,By,Bz,Ex,Ey,Ez,Pxx,Pyy,Pzz,POff1,POff2,POff3,T,Tpar,Tperp1,Tperp2,Tperp + +''' import sys import os diff --git a/scripts/gics.py b/scripts/gics.py index 7d0b30e8..4376457a 100644 --- a/scripts/gics.py +++ b/scripts/gics.py @@ -91,8 +91,10 @@ def E_horizontal(dB_dt, pos, time, sigma = 1e-3, method = 'liu'): Keywords: sigma = ground conductivity (siemens/meter) method: + 'liu': use integration method described in Liu et al., (2009) doi:10.1029/2008SW000439, 2009 this method is exact for piecewise linear B (i.e., piecewise constant dB/dt) + 'RH-riemann': use right-handed Riemann sum. ''' mu_0 = 1.25663706e-6 # permeability of free space diff --git a/scripts/magnetopause2d.py b/scripts/magnetopause2d.py index a204deb6..74a12872 100644 --- a/scripts/magnetopause2d.py +++ b/scripts/magnetopause2d.py @@ -1,3 +1,13 @@ +''' +running: +-takes two (or zero) commad line arguments: how many inner streamlines to ignore and from how many next to count the magnetopause position + +Some issues: +-Nose part unstable and slows the whole thing down, also requires lots of streamlines to work +-Bulk file change is hard and must be done by hand +-Everything else must also be done by changing the code by hand +''' + import pytools as pt import plot_colormap #gives error but doesn't work without import sys, os, socket @@ -13,15 +23,7 @@ import logging -''' -running: --takes two (or zero) commad line arguments: how many inner streamlines to ignore and from how many next to count the magnetopause position -Some issues: --Nose part unstable and slows the whole thing down, also requires lots of streamlines to work --Bulk file change is hard and must be done by hand --Everything else must also be done by changing the code by hand -''' diff --git a/scripts/magnetopause3d.py b/scripts/magnetopause3d.py index 5461a7d4..d758e234 100644 --- a/scripts/magnetopause3d.py +++ b/scripts/magnetopause3d.py @@ -1,3 +1,10 @@ +''' +Finds the magnetopause in 3D-run and plots it with matplotlib +Accepts 2 (or 0) command line arguments: 1) how many streamlines to ignore, 2) how many streamlines to count after the ignored ones + +output: +saves png-image to the current folder +''' import os import socket @@ -15,15 +22,6 @@ import ids3d import logging -''' -Finds the magnetopause in 3D-run and plots it with matplotlib -Accepts 2 (or 0) command line arguments: 1) how many streamlines to ignore, 2) how many streamlines to count after the ignored ones - -output: -saves png-image to the current folder -''' - - arcDeg = 10 # 360/arcDeg must be an integer. Best at 10, ok at 5, 10: 36 slices, 5: 72 slices @@ -431,6 +429,7 @@ def make_surface(coords): How it works: Three points make a triangle, triangles make the surface. + For every two planes next to each other: take every other point from plane1, every other from plane2 (in order!) from list of points: every three points closest to each other make a surface @@ -440,6 +439,7 @@ def make_surface(coords): plane 2: [v5, v6, v7, v8] -> list: [v1, v5, v2, v6, v3,...] + -> triangles: v1 v5 v2 v5 v2 v6 diff --git a/scripts/tsyganenko.py b/scripts/tsyganenko.py index d370375f..3f8e2ab8 100644 --- a/scripts/tsyganenko.py +++ b/scripts/tsyganenko.py @@ -30,8 +30,11 @@ def tsyganenko_trace(x0, y0, z0, Txx = 't01', InternalB='dipole', Dst = -30, Kp z0: initial z-coordinate (GSE) of field tracing [R_E] (float) --Keywords-- - Txx: (external) field model, by Tsyganenko publication year. options: 't89', 't96', 't01' + + Txx: + (external) field model, by Tsyganenko publication year. options: 't89', 't96', 't01' Need to test: does 't04' work? Is geomagnetic activity estimated with Kp or Dst in that case? + InternalB: internal model. options: 'dipole', 'igrf' Dst: Dst index in nT (geomagnetic activity), used for Txx= 't96', 't01' ('t04'?) Kp: Kp index 0-9 (geomagnetic activity), used for Txx='T89' @@ -42,9 +45,11 @@ def tsyganenko_trace(x0, y0, z0, Txx = 't01', InternalB='dipole', Dst = -30, Kp Bz_imf: driving solar wind GSE imf Bz [nT] (GSE) R_inner: inner radius [R_E] of the tracing, if the tracing goes rR_outer it stops + dir: direction of the tracing relative to the magnetic field direction (parallel: dir= 1, anti-parallel: dir= -1) If unspecified (dir=None), dir traces against the field when z0>0 with the field when z0<0 - *** this is the opposite convention used by geopack's trace() function? + + \\*\\*\\* this is the opposite convention used by geopack's trace() function? From geopack.py docs: "dir: Direction of tracing. dir = -1 for parallel; dir = 1 for anti-parallel." Returns: @@ -68,6 +73,7 @@ def tsyganenko_trace(x0, y0, z0, Txx = 't01', InternalB='dipole', Dst = -30, Kp Default solar wind and IMF parameters are for the EGI Vlasiator run, see Grandin et al. (2022?) Other runs: + EGL (note: pulse arrives at magnetopause at roughly t=857 sec) (~before pulse arrival): Dst = -30 (Grandin et al. 2022), N_sw = 1, Bz_imf = -5 (~after pulse arrival): Dst = -80 (Horaites et al.), N_sw = 4, Bz_imf = -10 @@ -201,6 +207,7 @@ def tsyganenko_ocb(phi, lat_range=[0,90], nsteps = 10, **kwargs): Inputs: phi: ~longitude, in degrees -180<=phi<=180 lat_range: 2-element list or numpy array, + containing min. and max. latidues [degrees] to search within -90<=lat<=90 kwargs are passed to tsyanenko_open() @@ -254,8 +261,10 @@ def tsyganenko_b(x, y, z, Txx = 't01', InternalB='dipole', Dst = -30, Kp = 4, Vx z0: z-coordinate(s) (GSE) to evaluate the field [R_E] (float) --Keywords-- + Txx: (external) field model, by Tsyganenko publication year. options: 't89', 't96', 't01' Need to test: does 't04' work? Is geomagnetic activity estimated with Kp or Dst in that case? + InternalB: internal model. options: 'dipole', 'igrf' Dst: Dst index in nT (geomagnetic activity), used for Txx= 't96', 't01' ('t04'?) Kp: Kp index 0-9 (geomagnetic activity), used for Txx='T89' @@ -266,9 +275,11 @@ def tsyganenko_b(x, y, z, Txx = 't01', InternalB='dipole', Dst = -30, Kp = 4, Vx Bz_imf: driving solar wind GSE imf Bz [nT] (GSE) R_inner: inner radius [R_E] of the tracing, if the tracing goes rR_outer it stops + dir: direction of the tracing relative to the magnetic field direction (parallel: dir= 1, anti-parallel: dir= -1) If unspecified (dir=None), dir traces against the field when z0>0 with the field when z0<0 - *** this is the opposite convention used by geopack's trace() function? + + \\*\\*\\* this is the opposite convention used by geopack's trace() function? From geopack.py docs: "dir: Direction of tracing. dir = -1 for parallel; dir = 1 for anti-parallel." Returns: @@ -293,6 +304,7 @@ def tsyganenko_b(x, y, z, Txx = 't01', InternalB='dipole', Dst = -30, Kp = 4, Vx Default solar wind and IMF parameters are for the EGI Vlasiator run, see Grandin et al. (2022?) Other runs: + EGL (note: pulse arrives at magnetopause at roughly t=857 sec) (~before pulse arrival): Dst = -30 (Grandin et al. 2022), N_sw = 1, Bz_imf = -5 (~after pulse arrival): Dst = -80 (Horaites et al.), N_sw = 4, Bz_imf = -10