Version 0.4.0 (#48)

* Fix bug exporting parametric models (#41)
* Pre-emphasis filter and loss (#42)
* WaveNet and CatWaveNet models (#43)
* Remove redundant `"nx"` in data set config; let the model provide it w/ its receptive field.
* Faster data indexing in `ConcatDataset`s with many data sets (#45)
* Improvements to the LSTM model.
* Version bump to 0.4.0.

Squash commit notes:

* Pencil in requirements

* Python package workflow

* install package, trigger on dev branch

* Quick ConvNet tests

* Colab Notebook test

* Fix Issue 15

* Update colab.ipynb

* Bump to version 0.2.1

* Should be good

* Update README.md

* Update README.md

* Parametric model (#26)

* Parametric data and Hypernet
* Validte data print path if fail
* Affine instead of layer norm, batchnorm momentum
* Tweak batchnorm momentum
* Fix test so data doesn't clip

* Exporting Hypernet models (#28)

* Export for HyperConvNet, tests

* Fix bool in CPP header

* DC loss (#32)

Closes #31

Implement DC loss of Eq. (19) of https://www.mdpi.com/2076-3417/10/3/766/htm, but without denominator term.

* ESR Loss (#33)

Closes #10

Energy-signal ratio loss metric of Eq. (10) of https://www.mdpi.com/2076-3417/10/3/766/htm

* tqdm loading data

* LSTM (#35)

Closes #24 

* Implement an LSTM model.
* Config with some decent starting parameters as well as some hints.
* Some improvements to the training script
* Some refactoring to model exporting

Squash of:

* Better callbacks

* Rearrange training input JSONs

* np_to_wav, expose REQUIRED_RATE

* LSTM model

* Version bump to 0.3.0

* Conditional LSTM (#38)

Closes #36 

* A conditional LSTM where the input signal is concatenated with the parametric inputs.
* Example configurations with helpful tips commented.
* Quality of life improvements in the trainer script including functionality for `ConcatDataset`-type validation datasets
* Slicing of a single pair of WAV files into datasets at different parametric settings.

Squash of:

* Better callbacks

* Rearrange training input JSONs

* np_to_wav, expose REQUIRED_RATE

* LSTM model

* Version bump to 0.3.0

* Plot ConcatDatasets

* Flatten datasets inside a ConcatDataset

* CatLSTM

* Tests

* Config for CatLSTM

* Better error message on invalid nx

* Fix export for parametric models (#40)

* Fix export for parametric models
* Version bump to 0.3.1

* Improve docstring

* WaveNet and other improvements (#46)

Smashing together a few things...

* Implements the WaveNet architecture (#43) (and the parametric version, concatenating the knobs as additional inputs i.e. "CatWaveNet")
* Speed up `ConcatDataset` access (#45)
* Deprecate use of `"nx"` in dataset config (#44)
* Increment version to 0.4.0

Commit notes:

* WaveNet

* Fix invalid broadcasting, rechannel needed

* CatWaveNet

* Faster lookup of data in ConcatDataset

* Gated, exporting weights work

* Fix bugs

* Fix export for parametric models

* Version bump to 0.3.1

* Exporting

* Move bias from the input mixer to the dilated conv, which is always used.

* Fix redundant conv in WaveNet head

* Fix bugs; works with plugin

* Automatically add nx to data config from model, check fewer than once per epoch

* Refactor for multiple layer sets

* Zero out through-connection for init (learn direct paths)

* Layer send to head before 1x1, remove zeroing init

* Fix bug: reintroduce out_length in head term

* Fix receptive field w/ non-2 kernel sizes

* Fix up WaveNet export

* cpp headers for WaveNet and CatWaveNet

* Improve docstring

* LSTM tweaks, etc (#47)

* Tweak default parameters of LSTM configs
* Pre-emphasis filtered loss (#42)
* LSTM export C++ header
* Improve printing on the training figures

* Update config files

* Update README.md

* Update README.md

* Update Colab notebook

* Update Colab notebook

.gitignore

@@ -130,7 +130,5 @@ dmypy.json
 # Pyre type checker
 .pyre/
 
-# etc
-data/
-.vscode/
-lightning_logs/
+# Training outputs
+./bin/train/outputs/

README.md

@@ -1,27 +1,45 @@
 # NAM: neural amp modeler
 
-This is the training part of NAM.
+This repository handles training, reamping, and exporting the weights of a model.
 For the code to create the plugin with a trained model, see my
 [iPlug2 fork](https://github.com/sdatkinson/iPlug2).
 
-This repository handles training, reamping, and exporting the weights of a model (to
-use with [the iPlug2 plugin]())
-
 ## How to use (Google Colab)
 
 If you don't have a good computer for training ML models, you can run the
 notebook located at `bin/train/colab.ipynb` in the cloud using Google Colab--no
 local installation required!
 
-Go to [colab.research.google.com](https://colab.research.google.com), open the
-notebook using the "GitHub" tab, and go!
+Go to [colab.research.google.com](https://colab.research.google.com), select the 
+"GitHub" tab, paste in the URL for the notebook 
+(https://github.com/sdatkinson/neural-amp-modeler/blob/dev/bin/train/colab.ipynb), 
+and go!
+
+**Pros:**
+* No local installation required!
+* Decent GPUs are available if you don't have one on your computer.
+
+**Cons:**
+* Uploading your data can take a long time.
+* The session will time out after an hour or so (for free accounts), so extended 
+  training runs aren't really feasible.  I've tried to set you up with a good
+  model that should train quickly!
 
 ## How to use (Local)
 
-Alternatively, the you can clone this repo and use it in the following ways on
-your own computer:
+Alternatively, you can clone this repo to your computer and use it locally.
+
+### Installation
+```bash
+conda env create -f environment.yml
+conda activate nam
+pip install .
+```
 
-### Train a model
+### Things you can do
+Here are the primary ways this is meant to be used:
+
+#### Train a model
 
 You'll need at least two mono wav files: the input (DI) and the amped sound (without the cab).
 You can either record enough to have a training and validation set in the same file and
@@ -43,7 +61,7 @@ bin/train/inputs/config_learning.json \
 bin/train/outputs/MyAmp
 ```
 
-### Run a model on an input signal ("reamping")
+#### Run a model on an input signal ("reamping")
 
 Handy if you want to just check it out without going through the trouble of building the
 plugin.
@@ -58,7 +76,7 @@ path/to/checkpoints/epoch=123_val_loss=0.000010.ckpt \
 path/to/output.wav
 ```
 
-### Export a model (to use with [the plugin](https://github.com/sdatkinson/iPlug2))
+#### Export a model (to use with [the plugin](https://github.com/sdatkinson/iPlug2))
 
 Let's get ready to rock!
 
@@ -73,18 +91,10 @@ You'll want the `HardCodedModel.h` to paste over into the plugin source (i.e. [h
 
 ## Advanced usage
 
-The model architecture in `config_model.json` should work plenty good. However, if you
-want to, you can increase the number of channels and the model will generally fit
-better (though it'll get closer to the threshold of real-time. 20 works for a "large"
-model and is still about 6x real time on my desktop).
-
-If you want to mess with the model architecture and end up with a different receptive
-field (e.g. by messing with the dilation pattern), then you need to make sure that `nx`
-is changed accordingly in the data setup.
-The default architecture has a receptive field of 8191 samples, so `nx` is `8191`.
-Generally, for the conv net architecture the receptive field is one elss than the sum of the `dilations`.
-
-You can train for shorter or longer.
-1000 gives pretty great results, but if you're impatient you can sometimes get away with
-comparable results after 500 epochs, and you might nto even be able to tell the
-difference with far fewer (maybe 200?...100?)
+The model architectures and cofigurations in `bin/train/inputs/models` should work plenty well out of the box. 
+However, feel free to play around with it; sometimes some tweaks can help improve performance.
+
+Also, you can train for shorter or longer.
+1000 epochs is typically overkill, but how little you can get away with depends on the model you're using.
+I recommend watching the checkpoints and keeping an eye out for when the ESR drops below 0.01--usually it'll
+sound pretty good by that point.

bin/export.py → bin/export/main.py

@@ -13,6 +13,8 @@
 import torch
 
 from nam.models import Model
+from nam.models._base import ParametricBaseNet
+from nam.models.parametric.catnets import Param
 
 
 class Dummy(torch.nn.Module):
@@ -21,20 +23,33 @@ def forward(self, x):
 
 
 def main(args):
+    outdir = Path(args.outdir)
     with open(args.model_config_path, "r") as fp:
         net = Model.load_from_checkpoint(
             args.checkpoint, **Model.parse_config(json.load(fp))
         ).net
+    if not isinstance(net, ParametricBaseNet):
+        export_args = (outdir,)
+    else:
+        if args.param_config is None:
+            raise ValueError("Require param config for parametric model")
+        with open(Path(args.param_config), "r") as fp:
+            param_config = {
+                k: Param.init_from_config(v) for k, v in json.load(fp).items()
+            }
+        export_args = (outdir, param_config)
     net.eval()
-    outdir = Path(args.outdir)
     outdir.mkdir(parents=True, exist_ok=True)
-    net.export(outdir)
-    net.export_cpp_header(Path(outdir, "HardCodedModel.h"))
+    net.export(*export_args)
+    net.export_cpp_header(Path(export_args[0], "HardCodedModel.h"), *export_args[1:])
 
 
 if __name__ == "__main__":
     parser = ArgumentParser()
     parser.add_argument("model_config_path", type=str)
     parser.add_argument("checkpoint", type=str)
     parser.add_argument("outdir")
+    parser.add_argument(
+        "--param-config", type=str, help="Configuration for a parametric model"
+    )
     main(parser.parse_args())