[A] Read, write and create SU data chapter in docs

CHANGELOG.md

@@ -10,6 +10,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.
 - *CHANGELOG.md* in docs/
 - *Interface with Geopsy-gpdc* in docs/
 - *Particle Swarm Optimization: basics* in docs/
+- *Read, write and create SU data* tutorial in docs/
+- **lib** folder for future C/Fortran libraries
 
 ### Modified
 - add __ZENODO__ DOI in the README.md

docs/html/PSO_basics.html

@@ -95,6 +95,7 @@
 <li class="toctree-l1"><a class="reference internal" href="nessi_modeling_interfaces.html">nessi.modeling.interfaces references</a></li>
 </ul>
 <ul class="current">
+<li class="toctree-l1"><a class="reference internal" href="read_write_and_create_SU_data.html">Read, write and create SU data</a></li>
 <li class="toctree-l1"><a class="reference internal" href="gpdc_interface.html">Interface with Geopsy-gpdc</a></li>
 <li class="toctree-l1 current"><a class="current reference internal" href="#">Particle Swarm Optimization: basics</a></li>
 </ul>

docs/html/_modules/index.html

@@ -93,6 +93,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../nessi_modeling_interfaces.html">nessi.modeling.interfaces references</a></li>
 </ul>
 <ul>
+<li class="toctree-l1"><a class="reference internal" href="../read_write_and_create_SU_data.html">Read, write and create SU data</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../gpdc_interface.html">Interface with Geopsy-gpdc</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../PSO_basics.html">Particle Swarm Optimization: basics</a></li>
 </ul>

docs/html/_modules/nessi/globopt/pso/swarm.html

@@ -93,6 +93,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../../../../nessi_modeling_interfaces.html">nessi.modeling.interfaces references</a></li>
 </ul>
 <ul>
+<li class="toctree-l1"><a class="reference internal" href="../../../../read_write_and_create_SU_data.html">Read, write and create SU data</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../../../gpdc_interface.html">Interface with Geopsy-gpdc</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../../../PSO_basics.html">Particle Swarm Optimization: basics</a></li>
 </ul>

docs/html/_modules/nessi/io/su_fmt.html

@@ -93,6 +93,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../../../nessi_modeling_interfaces.html">nessi.modeling.interfaces references</a></li>
 </ul>
 <ul>
+<li class="toctree-l1"><a class="reference internal" href="../../../read_write_and_create_SU_data.html">Read, write and create SU data</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../../gpdc_interface.html">Interface with Geopsy-gpdc</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../../PSO_basics.html">Particle Swarm Optimization: basics</a></li>
 </ul>

docs/html/_modules/nessi/modeling/interfaces/gpdcwrap.html

@@ -93,6 +93,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../../../../nessi_modeling_interfaces.html">nessi.modeling.interfaces references</a></li>
 </ul>
 <ul>
+<li class="toctree-l1"><a class="reference internal" href="../../../../read_write_and_create_SU_data.html">Read, write and create SU data</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../../../gpdc_interface.html">Interface with Geopsy-gpdc</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../../../PSO_basics.html">Particle Swarm Optimization: basics</a></li>
 </ul>

docs/html/_sources/index.rst.txt

@@ -42,6 +42,7 @@ Tutorials
 .. toctree::
     :maxdepth: 1
 
+    read_write_and_create_SU_data
     gpdc_interface
     PSO_basics
 

docs/html/_sources/read_write_and_create_SU_data.rst.txt

@@ -0,0 +1,104 @@
+
+Read, write and create SU data
+==============================
+
+The SU data format is a subset of the industrial standard SEG-Y. It
+consists in a binary trace header containing useful informations on the
+data such as: the number of time samples (ns), the time sampling (dt),
+the source and receiver positions (sx, sy, gx and gy), the position of
+the trace in the file and other fields to store metadata.
+
+Read a SU file
+--------------
+
+.. code:: ipython3
+
+    # Import the SUdata class from nessi.io module
+    from nessi.io import SUdata
+
+    # Declare
+    dobs = SUdata()
+
+    # Read the SU file
+    dobs.read('data/musc_F50_01.su')
+
+Access to metadata
+------------------
+
+The access to header is very simple since a valid keyword is provided.
+Some header values, such as ``dt``, are not in second and a scaling
+factor must be applied (please see Seismic Unix keyword documentation
+for more informations).
+
+.. code:: ipython3
+
+    # Get number of time samples and the time sampling
+    ns = dobs.header[0]['ns']
+    dt = dobs.header[0]['dt']/1000000.
+    print(ns, dt)
+
+
+.. parsed-literal::
+
+    12000 0.0001
+
+
+Header values can be directly modified, *i.e.* to modify the time
+sampling for all the traces:
+
+``dobs.header[:]['dt'] = new_value_in_seconds * 1000000.``
+
+Visualize data
+--------------
+
+Since many useful informations are stored in the SU header, plotting
+data is easy and the function's parameters are almost all related to the
+output image layout.
+
+.. code:: ipython3
+
+    # Import matplotlib
+    import matplotlib.pyplot as plt
+
+    # Show data
+    dobs.image(clip=0.05, label2='trace number', label1='time [s]', title='Visualize SU data', legend=1)
+    plt.show()
+
+
+
+.. image:: images/read_write_and_create_SU_data_01.png
+
+
+Write SU file on disk
+---------------------
+
+.. code:: ipython3
+
+    # Write a SU file
+    dobs.write('data/output.su')
+
+Create SU data
+--------------
+
+.. code:: ipython3
+
+    # Import numpy module
+    import numpy as np
+
+    # Create fake data using numpy with the time-axis along axis 1
+    ntrac_fake = 20
+    ns_fake = 10000
+    dt_fake = 0.0001
+    data_fake = np.zeros((ntrac_fake, ns_fake))
+
+    # Create a simple SU dataset with minimal informations (tracl, ns, dt) from a numpy array
+    dobs_fake = SUdata()
+    dobs_fake.create(data_fake, dt_fake)
+
+    # Check header values and the number of traces
+    print(dobs_fake.header[0]['ns'], dobs_fake.header[0]['dt']/1000000., np.size(dobs_fake.header, axis=0))
+
+
+.. parsed-literal::
+
+    [10000] [0.0001] 20

docs/html/changelog.html

@@ -29,7 +29,7 @@
   <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
     <link rel="index" title="Index" href="genindex.html" />
     <link rel="search" title="Search" href="search.html" />
-    <link rel="prev" title="Interface with Geopsy-gpdc" href="gpdc_interface.html" /> 
+    <link rel="prev" title="Particle Swarm Optimization: basics" href="PSO_basics.html" /> 
 
 
   <script src="_static/js/modernizr.min.js"></script>
@@ -89,13 +89,14 @@
 <li class="toctree-l1"><a class="reference internal" href="seismic_modeling_examples.html">Seismic modeling examples</a></li>
 <li class="toctree-l1"><a class="reference internal" href="sucwp_references.html">SU/CWP references</a></li>
 <li class="toctree-l1"><a class="reference internal" href="particle_swarm.html">Particle Swarm Optimization</a></li>
-<li class="toctree-l1"><a class="reference internal" href="notebooks/PSO_basics/PSO_basics.html">Particle Swarm Optimization: basics</a></li>
 <li class="toctree-l1"><a class="reference internal" href="interfaces.html">Interfaces</a></li>
 <li class="toctree-l1"><a class="reference internal" href="nessi_globopt.html">NeSSI global optimization module</a></li>
 <li class="toctree-l1"><a class="reference internal" href="nessi_modeling_interfaces.html">nessi.modeling.interfaces references</a></li>
 </ul>
 <ul>
+<li class="toctree-l1"><a class="reference internal" href="read_write_and_create_SU_data.html">Read, write and create SU data</a></li>
 <li class="toctree-l1"><a class="reference internal" href="gpdc_interface.html">Interface with Geopsy-gpdc</a></li>
+<li class="toctree-l1"><a class="reference internal" href="PSO_basics.html">Particle Swarm Optimization: basics</a></li>
 </ul>
 <ul class="current">
 <li class="toctree-l1 current"><a class="current reference internal" href="#">Changelog</a></li>
@@ -195,6 +196,8 @@ <h1>Changelog<a class="headerlink" href="#changelog" title="Permalink to this he
 ### Added
 - *CHANGELOG.md* in docs/
 - *Interface with Geopsy-gpdc* in docs/
+- *Particle Swarm Optimization: basics* in docs/
+- **lib** folder for future C/Fortran libraries
 
 ### Modified
 - add __ZENODO__ DOI in the README.md
@@ -273,7 +276,7 @@ <h1>Changelog<a class="headerlink" href="#changelog" title="Permalink to this he
     <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
 
 
-        <a href="gpdc_interface.html" class="btn btn-neutral" title="Interface with Geopsy-gpdc" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
+        <a href="PSO_basics.html" class="btn btn-neutral" title="Particle Swarm Optimization: basics" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
 
     </div>
 

docs/html/genindex.html

@@ -94,6 +94,7 @@
 <li class="toctree-l1"><a class="reference internal" href="nessi_modeling_interfaces.html">nessi.modeling.interfaces references</a></li>
 </ul>
 <ul>
+<li class="toctree-l1"><a class="reference internal" href="read_write_and_create_SU_data.html">Read, write and create SU data</a></li>
 <li class="toctree-l1"><a class="reference internal" href="gpdc_interface.html">Interface with Geopsy-gpdc</a></li>
 <li class="toctree-l1"><a class="reference internal" href="PSO_basics.html">Particle Swarm Optimization: basics</a></li>
 </ul>

docs/html/getting_started.html

@@ -94,12 +94,16 @@
 <li class="toctree-l1"><a class="reference internal" href="seismic_modeling_examples.html">Seismic modeling examples</a></li>
 <li class="toctree-l1"><a class="reference internal" href="sucwp_references.html">SU/CWP references</a></li>
 <li class="toctree-l1"><a class="reference internal" href="particle_swarm.html">Particle Swarm Optimization</a></li>
-<li class="toctree-l1"><a class="reference internal" href="notebooks/PSO_basics/PSO_basics.html">Particle Swarm Optimization: basics</a></li>
 <li class="toctree-l1"><a class="reference internal" href="interfaces.html">Interfaces</a></li>
 <li class="toctree-l1"><a class="reference internal" href="nessi_globopt.html">NeSSI global optimization module</a></li>
 <li class="toctree-l1"><a class="reference internal" href="nessi_modeling_interfaces.html">nessi.modeling.interfaces references</a></li>
 </ul>
 <ul>
+<li class="toctree-l1"><a class="reference internal" href="read_write_and_create_SU_data.html">Read, write and create SU data</a></li>
+<li class="toctree-l1"><a class="reference internal" href="gpdc_interface.html">Interface with Geopsy-gpdc</a></li>
+<li class="toctree-l1"><a class="reference internal" href="PSO_basics.html">Particle Swarm Optimization: basics</a></li>
+</ul>
+<ul>
 <li class="toctree-l1"><a class="reference internal" href="changelog.html">Changelog</a></li>
 </ul>
 

docs/html/gpdc_interface.html

@@ -29,8 +29,8 @@
   <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
     <link rel="index" title="Index" href="genindex.html" />
     <link rel="search" title="Search" href="search.html" />
-    <link rel="next" title="Changelog" href="changelog.html" />
-    <link rel="prev" title="nessi.modeling.interfaces references" href="nessi_modeling_interfaces.html" /> 
+    <link rel="next" title="Particle Swarm Optimization: basics" href="PSO_basics.html" />
+    <link rel="prev" title="Read, write and create SU data" href="read_write_and_create_SU_data.html" /> 
 
 
   <script src="_static/js/modernizr.min.js"></script>
@@ -90,13 +90,14 @@
 <li class="toctree-l1"><a class="reference internal" href="seismic_modeling_examples.html">Seismic modeling examples</a></li>
 <li class="toctree-l1"><a class="reference internal" href="sucwp_references.html">SU/CWP references</a></li>
 <li class="toctree-l1"><a class="reference internal" href="particle_swarm.html">Particle Swarm Optimization</a></li>
-<li class="toctree-l1"><a class="reference internal" href="notebooks/PSO_basics/PSO_basics.html">Particle Swarm Optimization: basics</a></li>
 <li class="toctree-l1"><a class="reference internal" href="interfaces.html">Interfaces</a></li>
 <li class="toctree-l1"><a class="reference internal" href="nessi_globopt.html">NeSSI global optimization module</a></li>
 <li class="toctree-l1"><a class="reference internal" href="nessi_modeling_interfaces.html">nessi.modeling.interfaces references</a></li>
 </ul>
 <ul class="current">
+<li class="toctree-l1"><a class="reference internal" href="read_write_and_create_SU_data.html">Read, write and create SU data</a></li>
 <li class="toctree-l1 current"><a class="current reference internal" href="#">Interface with Geopsy-gpdc</a></li>
+<li class="toctree-l1"><a class="reference internal" href="PSO_basics.html">Particle Swarm Optimization: basics</a></li>
 </ul>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="changelog.html">Changelog</a></li>
@@ -258,10 +259,10 @@ <h1>Interface with Geopsy-gpdc<a class="headerlink" href="#interface-with-geopsy
 
     <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
 
-        <a href="changelog.html" class="btn btn-neutral float-right" title="Changelog" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
+        <a href="PSO_basics.html" class="btn btn-neutral float-right" title="Particle Swarm Optimization: basics" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
 
 
-        <a href="nessi_modeling_interfaces.html" class="btn btn-neutral" title="nessi.modeling.interfaces references" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
+        <a href="read_write_and_create_SU_data.html" class="btn btn-neutral" title="Read, write and create SU data" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
 
     </div>
 

docs/html/index.html

@@ -94,6 +94,7 @@
 <li class="toctree-l1"><a class="reference internal" href="nessi_modeling_interfaces.html">nessi.modeling.interfaces references</a></li>
 </ul>
 <ul>
+<li class="toctree-l1"><a class="reference internal" href="read_write_and_create_SU_data.html">Read, write and create SU data</a></li>
 <li class="toctree-l1"><a class="reference internal" href="gpdc_interface.html">Interface with Geopsy-gpdc</a></li>
 <li class="toctree-l1"><a class="reference internal" href="PSO_basics.html">Particle Swarm Optimization: basics</a></li>
 </ul>
@@ -212,6 +213,7 @@ <h2>2D seismic modeling<a class="headerlink" href="#d-seismic-modeling" title="P
 <h2>Tutorials<a class="headerlink" href="#tutorials" title="Permalink to this headline">¶</a></h2>
 <div class="toctree-wrapper compound">
 <ul>
+<li class="toctree-l1"><a class="reference internal" href="read_write_and_create_SU_data.html">Read, write and create SU data</a></li>
 <li class="toctree-l1"><a class="reference internal" href="gpdc_interface.html">Interface with Geopsy-gpdc</a></li>
 <li class="toctree-l1"><a class="reference internal" href="PSO_basics.html">Particle Swarm Optimization: basics</a></li>
 </ul>

docs/html/interfaces.html

@@ -30,7 +30,7 @@
     <link rel="index" title="Index" href="genindex.html" />
     <link rel="search" title="Search" href="search.html" />
     <link rel="next" title="NeSSI global optimization module" href="nessi_globopt.html" />
-    <link rel="prev" title="Particle Swarm Optimization: basics" href="notebooks/PSO_basics/PSO_basics.html" /> 
+    <link rel="prev" title="Particle Swarm Optimization" href="particle_swarm.html" /> 
 
 
   <script src="_static/js/modernizr.min.js"></script>
@@ -90,7 +90,6 @@
 <li class="toctree-l1"><a class="reference internal" href="seismic_modeling_examples.html">Seismic modeling examples</a></li>
 <li class="toctree-l1"><a class="reference internal" href="sucwp_references.html">SU/CWP references</a></li>
 <li class="toctree-l1"><a class="reference internal" href="particle_swarm.html">Particle Swarm Optimization</a></li>
-<li class="toctree-l1"><a class="reference internal" href="notebooks/PSO_basics/PSO_basics.html">Particle Swarm Optimization: basics</a></li>
 <li class="toctree-l1 current"><a class="current reference internal" href="#">Interfaces</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="#geopsy-gpdc">Geopsy-gpdc</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#gprmax">gprMax</a></li>
@@ -100,6 +99,11 @@
 <li class="toctree-l1"><a class="reference internal" href="nessi_modeling_interfaces.html">nessi.modeling.interfaces references</a></li>
 </ul>
 <ul>
+<li class="toctree-l1"><a class="reference internal" href="read_write_and_create_SU_data.html">Read, write and create SU data</a></li>
+<li class="toctree-l1"><a class="reference internal" href="gpdc_interface.html">Interface with Geopsy-gpdc</a></li>
+<li class="toctree-l1"><a class="reference internal" href="PSO_basics.html">Particle Swarm Optimization: basics</a></li>
+</ul>
+<ul>
 <li class="toctree-l1"><a class="reference internal" href="changelog.html">Changelog</a></li>
 </ul>
 
@@ -209,7 +213,7 @@ <h2>gprMax<a class="headerlink" href="#gprmax" title="Permalink to this headline
         <a href="nessi_globopt.html" class="btn btn-neutral float-right" title="NeSSI global optimization module" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
 
 
-        <a href="notebooks/PSO_basics/PSO_basics.html" class="btn btn-neutral" title="Particle Swarm Optimization: basics" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
+        <a href="particle_swarm.html" class="btn btn-neutral" title="Particle Swarm Optimization" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
 
     </div>
 

docs/html/introduction.html

@@ -88,12 +88,16 @@
 <li class="toctree-l1"><a class="reference internal" href="seismic_modeling_examples.html">Seismic modeling examples</a></li>
 <li class="toctree-l1"><a class="reference internal" href="sucwp_references.html">SU/CWP references</a></li>
 <li class="toctree-l1"><a class="reference internal" href="particle_swarm.html">Particle Swarm Optimization</a></li>
-<li class="toctree-l1"><a class="reference internal" href="notebooks/PSO_basics/PSO_basics.html">Particle Swarm Optimization: basics</a></li>
 <li class="toctree-l1"><a class="reference internal" href="interfaces.html">Interfaces</a></li>
 <li class="toctree-l1"><a class="reference internal" href="nessi_globopt.html">NeSSI global optimization module</a></li>
 <li class="toctree-l1"><a class="reference internal" href="nessi_modeling_interfaces.html">nessi.modeling.interfaces references</a></li>
 </ul>
 <ul>
+<li class="toctree-l1"><a class="reference internal" href="read_write_and_create_SU_data.html">Read, write and create SU data</a></li>
+<li class="toctree-l1"><a class="reference internal" href="gpdc_interface.html">Interface with Geopsy-gpdc</a></li>
+<li class="toctree-l1"><a class="reference internal" href="PSO_basics.html">Particle Swarm Optimization: basics</a></li>
+</ul>
+<ul>
 <li class="toctree-l1"><a class="reference internal" href="changelog.html">Changelog</a></li>
 </ul>