Package: glaucus
GlaucusThe Aerospace Corporation is proud to present our complex-valued encoder,
decoder, and a new loss function for radio frequency (RF) digital signal
processing (DSP) in PyTorch.Video (click to play)UsingInstallvia PyPI:pip install glaucusvia source:pip install .Testingpytestcoverage runpylint glaucus testsUse pre-trained model with SigMF dataLoad quantized model and return compressed signal vector & reconstruction.
Our weights were trained & evaluated on a corpus of 200 GB of RF waveforms with
various added RF impairments for a 1 PB training set.importtorchimportsigmffromglaucusimportGlaucusAE# create modelmodel=GlaucusAE(bottleneck_quantize=True,data_format='nl')model=torch.quantization.prepare(model)# get weights for quantized modelstate_dict=torch.hub.load_state_dict_from_url('https://github.com/the-aerospace-corporation/glaucus/releases/download/v1.1.0/glaucus-512-3275-5517642b.pth',map_location='cpu')model.load_state_dict(state_dict)# prepare for predictionmodel.freeze()model.eval()torch.quantization.convert(model,inplace=True)# get samples into NL tensorx_sigmf=sigmf.sigmffile.fromfile('example.sigmf')x_tensor=torch.from_numpy(x_sigmf.read_samples())# create prediction & quint8 signal vectory_tensor,y_encoded=model(x_samples)# get signal vector as uint8y_encoded_uint8=torch.int_repr(y_encoded)Higher-accuracy pre-trained model# define architectureimporttorchfromglaucusimportblockgen,GlaucusAEencoder_blocks=blockgen(steps=6,spatial_in=4096,spatial_out=16,filters_in=2,filters_out=64,mode='encoder')decoder_blocks=blockgen(steps=6,spatial_in=16,spatial_out=4096,filters_in=64,filters_out=2,mode='decoder')# create modelmodel=GlaucusAE(encoder_blocks,decoder_blocks,bottleneck_in=1024,bottleneck_out=1024,bottleneck_quantize=True,data_format='nl')model=torch.quantization.prepare(model)# get weights for quantized modelstate_dict=torch.hub.load_state_dict_from_url('https://github.com/the-aerospace-corporation/glaucus/releases/download/v1.1.0/glaucus-1024-761-c49063fd.pth',map_location='cpu')model.load_state_dict(state_dict)# see above for restUse pre-trained model & discard quantization layers# create model, but skip quantizationfromglaucus.utilsimportadapt_glaucus_quantized_weightsmodel=GlaucusAE(bottleneck_quantize=False,data_format='nl')state_dict=torch.hub.load_state_dict_from_url('https://github.com/the-aerospace-corporation/glaucus/releases/download/v1.1.0/glaucus-512-3275-5517642b.pth',map_location='cpu')state_dict=adapt_glaucus_quantized_weights(state_dict)# ignore "unexpected_keys" warningmodel.load_state_dict(state_dict,strict=False)# prepare for evaluation modemodel.freeze()model.eval()# see above for restGet loss between two RF signalsimportnpimporttorchimportglaucus# create criterionloss=glaucus.RFLoss(spatial_size=128,data_format='nl')# create some signalxxx=torch.randn(128,dtype=torch.complex64)# alter signal with 1% freq offsetyyy=xxx*np.exp(1j*2*np.pi*0.01*np.arange(128))# return lossloss(xxx,yyy)Train model with TorchSigpartially implemented pending update or replace with notebook exampleimportlightningasplfromglaucusimportGlaucusAEmodel=GlaucusAE(data_format='nl')# this takes a very long time if no cache is availablesignal_data=torchsig.datasets.Sig53(root=str(cache_path))# 80 / 10 / 10 splittrain_dataset,val_dataset,test_dataset=torch.utils.data.random_split(signal_data,(len(signal_data)*np.array([0.8,0.1,0.1])).astype(int),generator=torch.Generator().manual_seed(0xcab005e))classRFDataModule(pl.LightningDataModule):'''defines the dataloaders for train, val, test and uses datasets'''def__init__(self,train_dataset=None,val_dataset=None,test_dataset=None,num_workers=16,batch_size=32):super().__init__()self.batch_size=batch_sizeself.num_workers=num_workersself.train_dataset=train_datasetself.val_dataset=val_datasetself.test_dataset=test_datasetdeftrain_dataloader(self):returnDataLoader(self.train_dataset,num_workers=self.num_workers,batch_size=self.batch_size,shuffle=True,pin_memory=True)defval_dataloader(self):returnDataLoader(self.val_dataset,num_workers=self.num_workers,batch_size=self.batch_size,shuffle=False,pin_memory=True)deftest_dataloader(self):returnDataLoader(self.test_dataset,num_workers=self.num_workers,batch_size=self.batch_size,shuffle=False,pin_memory=True)loader=RFDataModule(train_dataset=train_dataset,val_dataset=val_dataset,test_dataset=test_dataset,batch_size=batch_size,num_workers=num_workers)trainer=pl.Trainer()trainer.fit(model,loader)# rewind to best checkpointmodel.load_from_checkpoint(trainer.checkpoint_callback.best_model_path,strict=False)Pre-trained Model Listdesclinksize (MB)params (M)multiadds (M)provenancesmallglaucus-512-3275-5517642b8.52.030259.009 pfs-days on modulation-only Aerospace DSetaccurateglaucus-1024-761-c49063fd112.873380.035 pfs-days modulation & general waveform Aerospace Dsetsig53glaucus-1024-sig53TLe37-2956bcb6112.873380transfer learning from glaucus-1024-761-c49063fd w/Sig53 DsetNote on pfs-daysPerOpenAI appendixhere is the correct math (method 1):pfs_days= (add-multiplies per forward pass) * (2 FLOPs/add-multiply) * (3 for forward and backward pass) * (number of examples in dataset) * (number of epochs) / (flop per petaflop) / (seconds per day)(number of examples in dataset) * (number of epochs) = steps * batchsize1pfs-day≈ (8x V100 GPUs at 100% efficiency for 1 day) ≈ (100x GTX1080s at 100% efficiency for 1 day) ≈ (35x GTX 2080s at 100% efficiency for 1 day) ≈500 kWhPapersThis code is documented by the two following IEEE publications.Glaucus: A Complex-Valued Radio Signal AutoencoderA complex-valued autoencoder neural network capable of compressing & denoising radio frequency (RF) signals with arbitrary model scaling is proposed. Complex-valued time samples received with various impairments are decoded into an embedding vector, then encoded back into complex-valued time samples. The embedding and the related latent space allow search, comparison, and clustering of signals. Traditional signal processing tasks like specific emitter identification, geolocation, or ambiguity estimation can utilize multiple compressed embeddings simultaneously. This paper demonstrates an autoencoder implementation capable of 64x compression hardened against RF channel impairments. The autoencoder allows separate or compound scaling of network depth, width, and resolution to target both embedded and data center deployment with differing resources. The common building block is inspired by the Fused Inverted Residual Block (Fused-MBConv), popularized by EfficientNetV2 & MobileNetV3, with kernel sizes more appropriate for time-series signal processingComplex-Valued Radio Signal Loss for Neural NetworksA new optimized loss for training complex-valued neural networks that require reconstruction of radio signals is proposed. Given a complex-valued time series this method incorporates loss from spectrograms with multiple aspect ratios, cross-correlation loss, and loss from amplitude envelopes in the time & frequency domains. When training a neural network an optimizer will observe batch loss and backpropagate this value through the network to determine how to update the model parameters. The proposed loss is robust to typical radio impairments and co-channel interference that would explode a naive mean-square-error approach. This robust loss enables higher quality steps along the loss surface which enables training of models specifically designed for impaired radio input. Loss vs channel impairment is shown in comparison to mean-squared error for an ensemble of common channel effects.ContributingDo you have code you would like to contribute to this Aerospace project?We are excited to work with you. We are able to accept small changes
immediately and require a Contributor License Agreement (CLA) for larger
changesets. Generally documentation and other minor changes less than 10 lines
do not require a CLA. The Aerospace Corporation CLA is based on the well-knownHarmony Agreements CLAcreated by Canonical,
and protects the rights of The Aerospace Corporation, our customers, and you as
the contributor.You can find our CLA here.Please complete the CLA and send us the executed copy. Once a CLA is on file we
can accept pull requests on GitHub or GitLab. If you have any questions, please
e-mail us atoss@aero.org.LicensingThe Aerospace Corporation supports Free & Open Source Software and we publish
our work with GPL-compatible licenses. If the license attached to the project
is not suitable for your needs, our projects are also available under an
alternative license. An alternative license can allow you to create proprietary
applications around Aerospace products without being required to meet the
obligations of the GPL. To inquire about an alternative license, please get in
touch with us atoss@aero.org.To-Doallowpretrained_weightsduring model initadd training notebook and colab example