## Compound particle

This tutorial demonstrates how to construct complex shape particles.

All particles implemented in BornAgain are defined by their form factors, their sizes and the materials they are made of. The form factor library provides access to a list of about 20 elementary shapes. A special `Compound` object allows to compose elementary particles and their compositions into complex shapes and treat the resulting object as a single particle: it can be rotated, translated and included in the layer via a particle layout. The scattering from such a particle will account for coherent interference between sub particles.

### Creating particle composition

The `Compound` object is created via

    # creates an empty particle composition
    composition = ba.Compound()

The position of the particle defines the relative position of the particle’s reference point in the coordinate system of the particle composition.

`Compound` can be modified via following methods

    # add particle to the composition at specified position
    composition.addComponent(particle, position = R3(0,0,0))

    # add copies of the particles at specified positions
    composition.addComponents(particle, positions = [pos1, pos2, ...])

The existing composition can be composed to the new one:

    composition.addComponent(particle, pos1)
    composition.addComponent(compound, pos2)
    composition.addComponent(coreshell, pos3)
    composition.addComponent(mesocrystal, pos4)

### Examples

In following plot we demonstrate the creation of 3 different compositions

The hollow cross-shape on the left is constructed by adding four copies of the same box shaped particle at 4 different positions

    length, width, height = 10.0*nanometer, 10.0*nanometer, 3.0*nanometer
    box = Particle(box_material, Box(length, width, height))

    positions = [R3(length, 0, 0), R3(0, -width, 0), R3(-length, 0, 0), R3(0, width, 0)]
    composition = Compound()
    composition.addComponents(box, positions)

The stack of boxes at the center is constructed by placing 3 boxes made of different materials on top of each other.

    length, width, height = 10.0*nanometer, 10.0*nanometer, 5.0*nanometer
    ff_box = Box(length, width, height)

    composition = Compound()
    composition.addComponent(Particle(material1, ff_box), R3(0, 0, 0))
    composition.addComponent(Particle(material2, ff_box), R3(0, 0, height))
    composition.addComponent(Particle(material3, ff_box), R3(0, 0, 2.0*height))

The full sphere on the right is composed of two truncated spheres, each made of a different material. The bottom half is rotated first by 180 degrees about the Y axis before adding it to the composition.

    radius = 16.0*nanometer
    top_half = Particle(material1, SphericalSegment(radius, radius))
    bottom_half = Particle(material2, SphericalSegment(radius, radius))
    bottom_half.setRotation(RotationY(180.*degree))

    composition = Compound()
    composition.addComponent(top_half)
    composition.addComponent(bottom_half)

- Introduction
  - Functionality overview
  - Architectural overview

- Install or build
  - Install Python
    - Python on Linux
    - Python on Windows
    - Python on Mac
    - Python modules
  - Install BornAgain
    - Linux
    - Windows
    - MacOS
    - Development snapshot
  - Build BornAgain
    - Unix
      - Install third-party software
      - Get the source
      - Build and install BornAgain
      - Run a first simulation
    - Windows

- Graphical user interface
  - Quick Start
  - GUI overview
  - Fitting in the GUI

- Python scripting
  - Run a script
  - Understand the syntax
  - Fitting
  - Upgrading

- Reference
  - Simulation model
    - Simulation classes
      - Specular
        - Example
      - Scattering
        - Examples
          - GISAS
          - without DWBA terms
          - with specular peak
          - SAS
          - Polarized SANS
          - Monte-Carlo
      - Off-specular
        - Off-specular
      - Depth probe
        - Examples
          - Thin film
          - Transmitted modulus
          - Resonator
    - Common settings
      - Background
      - Options
        - Monte-Carlo
        - # threads
        - Average materials
        - Include specular
      - Progress monitor
  - Instrument model
    - Beam
      - Footprint
      - Beam divergence
    - Scan
      - TOF reflectometry
      - TOF resolution
      - Beam Angular Spread
      - Beam Wavelength Spread
    - Detectors
      - SphericalDetector
      - 2d detector resolution
      - Offspec detector
    - Neutron polarization
      - Spin asymmetry example
    - Examples
      - 2D detector resolution
      - Neutron polarization
        - Magnetic layer
        - Ditto, realistic instrument
        - Polarized scattering
  - Sample model
    - Materials
      - Magnetization
    - Sample
      - Layer
      - LayerStack
      - Layout
    - Roughness
      - Interface model
      - Transient
      - Cross-correlation
      - Examples
        - GISAS
        - Reflectivity
    - Particles
      - Form factor
        - Hard particles
          - Bipyramid4
          - Box
          - CantellatedCube
          - Cone
          - Cylinder
          - Dodecahedron
          - EllipsoidalCylinder
          - HemiEllipsoid
          - HorizontalCylinder
          - Icosahedron
          - PlatonicOctahedron
          - PlatonicTetrahedron
          - Prism3
          - Prism6
          - Pyramid2
          - Pyramid3
          - Pyramid4
          - Pyramid6
          - Sphere
          - SphericalSegment
          - Spheroid
          - SpheroidalSegment
          - TruncatedCube
        - Ripples
          - Bar ripple
          - Cosine ripple
          - Sawtooth ripple
        - Soft particles
          - FuzzySphere
          - Gauss
        - Custom formfactor
      - Composite particles
        - Core and shell
        - Compound particle
        - Mesocrystal
      - Examples
        - Compound particle
        - Core and shell
        - Crossing an interface
        - Mesocrystal
        - Rotation example
        - Dense cylinders
        - Dense hemispheres
        - Uncorrelated mixture
        - Polydispersity
    - Particle assemblies
      - Grating
        - 1D lattice
        - Cosine ripples in a lattice
        - Triangular ripples in a lattice
      - 2D lattice
        - Square lattice
        - Lattice orientation distribution
        - Finite square lattice
        - Lattice with basis
        - Multi-layer lattice
        - Position variance
      - Radial paracrystal
      - 2D paracrystal
      - Others
        - Size-distribution model: decoupling approximation
        - Size-distribution model: local monodisperse approximation
        - Size-distribution model: size-spacing coupling approximation
  - Model modifiers
    - Rotation
    - Distributions
  - Data types
    - Class Datafield
      - Export
      - Find intensity peaks
    - SLD profile
      - SLD profile with rough interfaces
      - SLD profile with a sliced particle layer
  - Plotting
    - Functions
    - Configuration
    - Heat map
    - LaTeX markup
    - Export
    - Plot axes in different units
  - Fitting
    - Data import
      - TIFF
    - Minimizer settings
    - Multiple datasets
    - Examples
      - Fitting with masks
      - Custom objective function
      - Fitting along slices
      - GISAS 2D fits
      - Experiment at GALAXI
      - Find background
      - Minimizer settings
      - Bayesian Sampling
      - Consecutive fitting
      - Considering uncertainties
      - External minimizer
      - External minimizer: plotting
      - Simultaneous fit of two datasets
      - Spin asymmetry fit example
      - Reflectometry: Fit Pt layer
      - Reflectometry: Fit honeycomb

- Literature
  - Babonneau2010
  - Babonneau2013
  - Croset2021
  - Lazzari2002
  - Lazzari2006
  - Pospelov2020
  - Renaud2009
  - Sears1992
  - Wuttke2021

- How to
  - Get announcements
  - Solve known problems
    - Set Python environmental variables under Windows
  - Request help or report bugs
  - Cite BornAgain

- Developers' corner
  - Configure
    - Build
    - Pyenv
  - Develop
    - Manual checks
    - Debug
    - Webdoc
    - Code analyses
  - Release
    - Manual GUI test